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Chapter 1. Installable File System Mechanism 


The OS/2 Installable File System (IFS) Mechanism supports the following: 
Coexistence of multiple, active file systems in a single PC 
Multiple logical volumes (partititions) 

Multiple and different storage devices 
Redirection or connection to remote file systems 

File system flexibility in managing its data and I/O for optimal performance 

Transparency at both the user and application level 

Standard set of File I/O API 

Existing logical file and directory structure 

Existing naming conventions 

File system doing its own buffer management 

File system doing file I/O without intermediate buffering 

Extensions to the Standard File I/O API (FSCTL) 

Extensions to the existing naming conventions 

IOCTL type of communication between a file system and a device driver 


Installable File System Overview 
System Relationships 

The Installable File System (IFS) Mechanism defines the relationships among the 
operating system, the file systems, and the device drivers. The basic model of the 
system is represented in Figure 1-1 on page 1-2. 


© Copyright IBM Corp. 1991 


1-1 


File System Request Router 


I I 

1 | 1 | 1| | 

File | | File | | File || | 

System | | System | | System || 

'll II II I 

LOCAL | | NET | | NET || 

| | REDIR1 | | REDIR2 || 


FS Helper Routines/ 

Device Driver Request Router 


Device | | Device | | Device || 

Driver | | Driver | | Driver || 


Device Driver Helper Routines 


Figure 1-1. System relationships for Installable File Systems 

The file system request router directs file system function calls to the appropriate 
file system for processing. 

The file systems manage file I/O and control the format of information on the 
storage media. An installable file system (FS) will be referred to as a file system 
driver (FSD). 

The FS Helper Routines provide a variety of services to the file systems. 

The device drivers manage physical I/O with devices. Device drivers do not under- 
stand the format of information on the media. 


File I/O API 

Standard file I/O is performed through the Standard File I/O API. The application 
makes a function call and the file system request router passes the request to the 
correct file system for processing. See Figure 1-2 on page 1-3. 
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Figure 1-2. Standard File I/O 
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New API may be provided by a file system to implement functions specific to the 
file system or not supplied through the standard file I/O interface. New API are 
provided in a dynamic link library that uses the DosFsCtl standard function call to 
communicate with the specific file system (FSD). See Figure 1-3. 


| application | 
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[ for File System X | 
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DosFsCtl | Standard File I/O API 
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Figure 1-3. Extended File I/O 
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Buffer Management 

In 2.0 the FAT buffer management helpers were removed because of lack of use 
by any 1.x FSD. FSDs should handle all buffer/cache management themselves. 

The FSD moves all data requiring partial sector I/O between the application’s 
buffers and its cache buffers. The FS helper routines initiate the I/O for local file 
systems. 

Volume Management 

Volume management (that is, detecting when the wrong volume is mounted and 
notifying the operator to take corrective action) is handled directly through OS/2 and 
the device driver. Each FSD is responsible for generating a volume label and 
32-bit volume serial number. These are stored in a reserved location in logical 
sector zero at format time. Because an FSD is the only system component to 
touch this information, an FSD is not required to store it in a particular format. 

OS/2 calls the FSD to perform operations that might involve it. The FSD is 
required to update the volume parameter block (VPB ) whenever the volume label 
or serial number is changed. 

When the FSD passes an I/O request to an FS helper routine, the FSD passes the 
32-bit volume serial number and the user’s volume label (through the VPB). When 
the I/O is performed, OS/2 compares the requested volume serial number with the 
current volume serial number it maintains for the device. This is an in-storage test 
(no I/O required) performed by checking the drive parameter block’s (DPB) VPB of 
the volume mounted on the drive. If unequal, OS/2 signals the critical error handler 
to prompt the user to insert the volume having the serial number and label speci- 
fied. 

When OS/2 detects a media change in a drive, or the first time a volume is 
accessed, OS/2 determines which FSD is responsible for managing I/O to that 
volume. OS/2 allocates a VPB and polls the installed FSDs (by calling the 
FSJVIOUNT entry point) until an FSD indicates that it does recognize the media. If 
the volume serial number and label returned by the FS_MOUNT call matchs the 
serial number and label in an existing VPB, OS/2 will call FS_MOUNT to unmount 
the new access and will continue to access the media through the previous VPB. 

Note: The FAT FSD is the last in the list of installed FSDs and acts as the default 
FSD when no other FSD recognition takes place. 


Connectivity 

There are two classes of file system drivers: 

FSDs that use a block device driver to do I/O to a local or remote device. 

These are called local file systems. 

FSDs that access a remote system without a block device driver. These are 
called remote file systems 

The connection between a drive letter and a remote file system is achieved through 
a command interface provided with the FSD (FS_Attach). 

When a local volume is first accessed, OS/2 sequentially asks each installed FSD 
to accept the media, by calling each FSD’s FS_MOUNT entry point. If no FSD 
accepts the media, it is then assigned to the default FAT file system. Any further 
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attempt that is made to access an unrecognized media, other than by FORMAT, 
results in an ’Invalid media format’ message. 


When a volume has been recognized, the relationship between drive, FSD, volume 
serial number, and volume label is remembered. The volume serial number and 
label are stored in the volume parameter block (VPB). The VPB is maintained by 
OS/2 for open files (I/O based on file-handles), searches, and buffer references. 
The VPB represents the media. 

Subsequent requests for a volume that has been removed require polling the 
installed FSDs for volume recognition by calling FSJVIOUNT. The volume serial 
number and volume label of the VPB returned by the recognizing FSD and the 
existing VPB are compared. If the test fails, OS/2 signals the critical error handler 
to prompt the user for the correct volume. 

The connection between media and VPB is remembered until all open files on the 
volume are closed and search and cache buffer references are removed. Only 
volume changes cause a redetermination of the media at the time of next access. 


IPL Mechanism 

If Boot Manager is not installed, a primary DOS disk partition (type 1, 4, or 6) may 
be used to boot the system. If Boot Manager is installed, a logical partition may 
contain the code to boot OS/2, but the boot code can not be located beyond cyl- 
inder 1024 since BIOS is used to read the disk prior to loading the device driver(s). 
The code for FSDs may reside in any partition readable by a previously installed 
FSD. An IFS partition must be a type 7 partition. 

The OS/2 boot volume will have a Bootrecord at logical sector 0 which will invoke 
the basic file system code to start the loading process. The root directory of this 
volume will contain a mini-file system in OS2BOOT, a kernel loader in OS2LDR, 
the OS/2 kernel in OS2KRNL, and the CONFIG.SYS file. 

Device drivers and FSDs are loaded in the order they appear in CONFIG.SYS and 
are considered elements of the same ordered set. Therefore, both device drivers 
and FSDs may be loaded from installed file systems as long as they are started in 
the proper order. For example: 

DEVICE = c:\diskdriv.sys 

REM Block device D: is now defined, (diskdriv.sys controls this.) 

IFS = c:\fsd\newfsl.fsd 

REM If we assume that D: contains a fixed newfsl type partition, 

REM then we’re now ready to use D: to load the device driver and 
REM FSD for E:. 

DEVICE = d:\root\dev\special.dev 
REM Block device e: is now defined. 

IFS = d:\root\fsd\special.fsd 
REM E: can now be read. 

DEVICE = e:\music 

OS/2 Partition Access 

Access to the OS/2 partition on a bootable, logically partitioned media is through 
the full OS/2 function set. See OS/2 Version 3.0 Physical Device Driver Reference 
for a detailed description of the disk partitioning design. 
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Permissions 

There are no secure file system clients identified for OS/2 Version 3.0 incorporating 
the IFS architecture. 

File Naming Conventions 

See OS/2 Version 3.0 Programming Guide for a detailed description of OS/2 
Version 3.0 file naming conventions. 

It is currently a requirement that an FSD supports case insensitive searching if they 
are to be completely compatible with OS/2. The large number of DOS, Windows 
and OS/2 applications that depend on case insensitive searching make it unlikely 
that this requirement will be removed. At this time, problems caused by an FSD 
only supporting case sensitive searching are the responsibity of the owners of the 
FSD. 

Meta Character Processing 

See OS/2 Version 3.0 Programming Guide for a detailed description of OS/2 
Version 3.0 meta character processing. 

FSD Pseudo-character Device Support 

A pseudo-character device (single file device) may be redirected to an FSD. The 
behavior of this file is very similar to the behavior of a normal OS/2 character 
device. It may be read from (DosRead) and written to (DosWrite). The difference 
is that the DosChgFilePtr and DosFileLocks functions can also be applied to the 
file. The user would perceive this file as a device name for a non-existing device. 
This file is seen as a character device because the current drive and directory have 
no effect on the name. That is what happens in OS/2 today for character devices. 

The format of an OS/2 pseudo-character device name is that of an ASCIIZ string in 
the format of an OS/2 file name in a subdirectory called \DEVY The pseudo device 
name XXX is acccessible at the API level (DosQFsAttach) through the path name 
’\DEV\XXX’. 

Family API Issues 

Since the IFS Mechanism is not present in any release of DOS, FAPI will not be 
extended to support the new interfaces. 


FSD Utilities 


FSD Utility Support 

Each FSD is required to provide a single .DLL executable module that supports the 
OS/2 FORMAT, CHKDSK, SYS, and RECOVER utilities. The FS-supported exe- 
cutable will be invoked by these utilities when performing a FORMAT, CFIKDSK, 
SYS, or RECOVER function for that file system. The command line that was 
passed to the utility will be passed unchanged to the FS-specific executable. 

The procedures that support these utilities reside in a file called U<fsdname>.DLL, 
where <fsdname> is the name returned by DosQFsAttach. Since in OS/2 Version 
3 DLL names are limited to 8.3, <fsdname> should be a maximum of 7 bytes long. 
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FSD Utility Guidelines 

The FSD utility procedures are expected to follow these guidelines: 

No preparation is done by the base utilities before they invoke the FSD utility 
procedure. Therefore, base utilities do not lock drives, parse names, open 
drives, etc. This allows maximum flexibility for the FSD. 

The FSD utility procedure is expected to protect the partition from access if 
they are doing direct access updates. The category 8 DoslOCTLs 
DSK_LOCKDRIVE and DSK_UNLOCKDRIVE should be used to protect the 
drive from access. The DSK_REDETERMINEMEDIA call must be made after 
FORMAT if the volume label and/or serial number has been modified- it will 
allow the VPB and DPB to be updated appropriately. 

The FSD utility procedures are expected to follow the standard conventions for 
the operations that they are performing, for example, / F for CFIKDSK implies 
’’fix” and the /L for FORMAT implies a long or certified format. All functional 
levels are not required, but if an equivalent function is supplied, the same 
parameter should be used. 

The FSD procedures may use stdin, stdout, and stderr, but should be aware 
that they may have been redirected to a file or device. 

It is the responsibility of the FSD procedures to worry about volumes being 
changed while the operation is in progress. The normal action would be to 
stop the operation when such a situation is detected. 

When the FSD procedures are called, they will be passed argc, argv, and envp, 
that they can use to determine the operations. 

FSD procedures are responsible for displaying relevant prompts and messages. 

FSD utility procedures must follow the standard convention of entering the 
target drive as specified for each utility. 

FSD Utility Interfaces 

All FSD utility procedures are called with the same arguments: 

int far pascal Ufsdname.CHKDSK(int argc, char far Vfar hrgv, 
char far Tar fenvp); 

int far pascal Ufsdname.FORMAT(int argc, char far Tar hrgv, 
char far Tar tenvp); 

int far pascal Ufsdname.RECOVER(int argc, char far Tar hrgv, 
char far Tar tenvp); 

int far pascal Ufsdname.SYS(int argc, char far Tar hrgv, 
char far Tar fenvp); 

where argc, argv, and envp have the same semantics as the corresponding vari- 
ables in C. 


Extended Attributes 

Extended attributes (EAs) are a mechanism whereby an application can attach 
information to a file system object (directories or files) describing the object to 
another application, to the operating system, or to the FSD managing that object. 
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EAs associated with a file object are not part of a file object's data, but are main- 
tained separately and managed by the file system that manages that object. 

Each extended attribute consists of a name and a value. An EA name consists of 
ASCII text, chosen by the application developer, that is used to identify a particular 
EA. EA names are restricted to the same character set as a filename. An EA 
value consists of arbitrary data, that is, data of any form. Because of this OS/2 
does not check data that is associated with an EA. 

So that EA data is understandable to other applications, conventions have been 
established for: 

Naming EAs 

Indicating the type of data contained in EAs 

In addition, a set of standard EAs (SEAs) have been defined. SEAs define a 
common set of information that can be associated with most files (for example, file 
type and file purpose). Through SEAs, many applications can access the same, 
useful information associated with files. 

Applications are not limited to using SEAs to associate information with files. They 
may define their own application-specific extended attributes. Applications define 
and associate extended attributes with a file object through file system function 
calls. 

See the OS/2 Version 3.0 Programming Guide for a complete description of EA 
naming conventions and data types and standard extended attributes. See also the 
OS/2 Version 3.0 Control Program Programming Reference for a complete 
description of the file system function calls. 

EAs may be viewed as a property list attached to file objects. The services for 
manipulating EAs are: add/replace a series of name/value pairs, return name/value 
pairs given a list of names, and return the total set of EAs. 

There are two formats for EAs as passed to OS/2 Version 3.0 API: Full EAs (FEA) 
and Get EAs (GEA). 


FEAs 

FEAs are complete name/value pairs. In order to simplify and speed up scanning 
and processing of these names, they are represented as length-preceded data. 
FEAs are defined as follows: 

struct FEA { 

unsigned char fEA; Abyte of flags X 
unsigned char cbName; //length of name X 
unsigned short cbValue; //length of value X 
unsigned char szNamef ]; Aasciiz name X 
unsigned char aValuej ]; Afree format value X 


There is only one flag defined in fEA at this time. That is 0x80 which is fNeedEA. 
Setting the flag marks this EA as needed for the proper operation on the file to 
which it is associated. Setting this bit has implications for access to this file by old 
applications, so it should not be set arbitrarily. 

If a file has one or more NEED EAs, old applications are not allowed to open the 
file. For DOS mode applications to access files with NEED EAs, they must have 
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the EA bit set in their exe header. For OS/2 mode, only applications with the 
NEWFILES bit set in the exe header may open files with NEED EAs. The OS/2 
IFS mechanism supports this restriction using the information in the pfgenflag 
returned by the FS_OPENCREATE routine. 

The name length does not include the trailing NUL. The maximum EA name length 
is 255 bytes. The minimum EA name length is 1 byte. The characters that form 
the name are legal filename characters. Wildcard characters are not allowed. EA 
names are case-insensitive and should be uppercased. The FSD should call 
FSH_CHECKEANAME and FSH_UPPERCASE for each EA name it receives to 
check for invalid characters and correct length, and to uppercase it. 

The FSD may not modify the flags. 

A list of FEAs is a packed set of FEA structures preceded by a length of the list 
(including the length itself) as indicated in the following structure: 

struct FEAList { 

unsigned long cbList; //length of list X 

struct FEA list[ ]; Apacked set of FEAs X 

}; 

FEA lists are used for adding, deleting, or changing EAs. A particular FSD may 
store the EAs in whatever format it desires. Certain EAs may be stored to optimize 
retrieval. 

Name lengths of 0 are illegal and are considered in error. A value length of 0 has 
special meaning. Setting an EA with a value length of 0 will cause that attribute to 
be deleted (if possible). Upon retrieval, a value length of 0 indicates that the attri- 
bute is not present. 

Setting attributes contained in an FEA list does not treat the entire FEA list as 
atomic. If an error occurs before the entire list of EAs has been set, all, some, or 
none of them may actually remain set on the file. No program should depend on 
an EA set being atomic to force EAs to be consistent with each other. Programs 
must be careful not to depend on atomicity, since a given file system is not required 
to provide it. 


GEAs 

A GEA is an attribute name. Its format is: 

struct GEA { 

unsigned char cbName; //length of name X 

unsigned char szNamef ]; Aasciiz name X 

}; 

The name length does not include the trailing NUL. 

Name lengths of 0 are illegal and are considered in error. 

A list of GEAs is a packed set of GEA structures preceded by a length of the list 
(including the length itself) as indicated in the following structure: 

struct GEAList { 

unsigned long cbList; //length of list X 
struct GEA list[ ]; Apacked set of GEAs X 

}; 
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GEA lists are used for retrieving the values for a particular set of attributes. A GEA 
list is used as input only. 

Manipulation of extended attributes is associated with access permission to the 
associated file or directory. For querying and setting file EAs, read and write/read 
permission, respectively, for the associated file is required. No directory create or 
delete will occur while querying EAs for that directory. 

For handle-based operations on extended attributes, access permission is con- 
trolled by the sharing/access mode of the associated file. If the file is open for 
read, querying the extended attributes is allowed. If the file is open for write, 
setting the extended attributes is allowed. These operations are supported by the 
FSD in FS_FILEINFO. OS/2 will provide the sharing/access checks for the FSD. 

For path-based manipulation of extended attributes, the associated file or directory 
will be added to the sharing set for the duration of the call. The requested access 
permission for setting EAs is write/deny-all and for querying EAs is read/deny-write. 
The path-based API are DosQPathlnfo, DosSetPathlnfo, and DosFindFirst2/Next. 
These API map to FS_PATHINFO, FS_FINDFIRST, FS_FINDNEXT and 
FS_FINDFROMNAME. 

For create-only operations of extended attributes, the extended attributes are set 
without examining the sharing/access mode of the associated file/directory. These 
operations are performed by APIs DosOpen2 and DosMkDir2 which result in calls 
to FS_OPENCREATE and FSJVIKDIR respectively. 

The routing of EA requests is accomplished by the IFS routing mechanism. EA 
requests that apply to names are routed to the FSD attached to the specified drive. 
Those requests that apply to a handle (file or directory) are routed to the FSD 
attached to the handle. No interpretation of either FEA lists nor GEA lists is per- 
formed by the IFS router. 

Note: It is the responsibility of each FSD to provide support for EAs. 

It is expected that some FSDs will be unable to store EAs; for example, UNIX- and 
MVS-compatible file systems. However, the growing use of EAs in applications- 
especially the object-oriented applications means there will be reduced functionality 
if an FSD does not support EAs. 

Note: The FAT FSD implementation will provide for the complete implementation 
of EAs. There will be no special EAs for the FAT FSD. 

All EA manipulation is performed using the following structure: The relevance of 
each field is described within each API. 

struct EAOP { 

struct GEAList far YfpGEAList; AGEA set X 

struct FEAList far XfpFEAList; AFEA set X 

unsigned long offError; Aoffset of FEA err X 

}; 

See the descriptions of the file system function calls in OS/2 Version 3.0 Control 
Program Programming Reference for the relevance of each field. 

In OS/2 Version 3.0, values of cbList greater than (64K-1) are not allowed. This 
limitation is caused by the requirement of supporting the FS_FILEINFO and 
FS_PATHINFO level 4 call to return all EAs. Until this interface changes or file 
systems are converted to 32 bit, this limitation is expected to continue. It is the 
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responsibility of the FSD to not permit extended attributes to be added so that the 
entire extended attribute set exceeds 64K. This will prevent the level 4 
FS_FILEINFO and FS_PATHINFO query from overflowing.. 


FSD File Image 

An FSD loads from a file which is in the format of a standard OS/2 dynamic link 
library file. Exactly one FSD resides in each file. The FSD exports information to 
OS/2 using a set of predefined public names. 

The FSD is initialized by a call to the exported entry point FSJNIT. 

FS entry points for Mount, Read, Write, etc. are exported with known names as 
standard far entry points. 

The FSD exports its name as a public ASCIIZ character string under the name 
’FS_NAME’. All comparisons with user-specified strings are done similar to file 
names; case is ignored and embedded blanks are significant. FS_NAMEs, 
however, may be input to applications by users. Embedded blanks should be 
avoided. The name exported as FSJ4AME need NOT be the same as the 1-8 
FSD name in the boot sector of formatted media, although it may be. The ONLY 
name the kernel pays any attention to, and the only name accessible to user pro- 
grams through the API, is the name exported as FS^NAME. 

In addition to various entry points, the FSD must export a dword bit vector of attri- 
butes. Attributes are exported under the name ’FS_ATTRIBUTE’. FS_ATTRIBUTE 
specifies special properties of the FSD and is described in the next section. 


FSD Attribute 

The format of the OS/2 FS_ATTRIBUTE is defined in Figure 1-4 and the definition 
list that follows it. 
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Figure 1-4. OS/2 FSD Attribute 


Bits Description 

31 FSD Additional attributes. If 1, FSD has additional attributes. 

If 1, FSD has additional attributes. If 0, FS_ATTRIBUTE is the only FSD 
attribute information. 
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30-28 VERSION NUMBER - FSD version number. 

27-5 RESERVED 

4 FSA_PSVR - Remote Pipe bit. 

Set if FSD manages remote pipes. 

3 FSA_LVL7 - QPathlnfo Level 7 bit. 

Set if FSD is case-preserving. If this bit is set, the kernel will call the 
FS_PATHINFO entry point with a level equal to 7. The output buffer is to 
be filled with a case-preserved copy of the path that was passed in by the 
user. 

2 FSA_LOCK - File I/O bit. 

Set if FSD wants to see file locking/unlocking operations and compacted 
file I/O operations. If not set, the file I/O calls will be broken up into indi- 
vidual lock/unlock/read/write/seek calls and the FSD will not see the 
lock/unlock calls. FSDs that do not support file locking can set this bit to 
enable compacted file I/O operations. FSDs that do support file locking 
will be responsible for all lock checking; OS/2 will not perform any 
checking for locks if this bit is set. The FSD will be responsible for han- 
dling the contention between multiple processes due to file locking- in 
other words, the FSD is responsible for preventing deadlocks. Since DOS 
applications use FS_FILEIO and OS/2 applications use FS_FILELOCKS, 
the FSD will need to support both entry points if it needs to support file 
locking under both DOS and OS/2. 

1 FSA_UNC - Universal Naming Convention bit. Set if FSD supports 

Set if FSD supports the Universal Naming Convention. OS/2 Version 3.0 
supports multiple loaded UNC redirectors. 

0 FSA_REMOTE - Remote File System(Redirector). 

This bit tells the system whether the FSD uses static or dynamic media 
attachment. Local FSDs always use dynamic media attachment. Remote 
FSDs always use static media attachment. This bit is clear if it is a 
dynamic media attachment and set, if a static attachment. No FSD sup- 
ports both static and dynamic media attachment. To support proper file 
locking, a remote FSD should also set the FSA_LOCK bit. 


FSD Initialization 

FSD initialization occurs at system initialization time. FSDs are loaded through the 
IFS= configuration command in CONFIG.SYS. Once the FSD has been loaded, 
the FSD’s initialization entry point is called to initialize it. 

FSDs are structured the same as dynamic link library modules. Once an FSD is 
loaded, the initialization routine FSJNIT is called. This gives the FSD the ability to 
process any parameters that may appear on the CONFIG.SYS command line, 
which are passed as a parameter to the FSJNIT routine. A LIBINIT routine in an 
FSD will be ignored. 

OS/2 FSDs initialize in protect mode. Because of the special state of the system, 
an FSD may make dynamic link system calls at init-time. 

The list of systems calls that an FSD may make are as follows: 
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DosBeep 

DosChgFilePtr 

DosClose 

DosDelete 

DosDevConfig 

DosDevloCtl 

DosFindClose 

DosFindFirst 

DosFindNext 

DosGetEnv 

DosGetlnfoSeg 

DosGetMessage 

DosOpen 

DosPutMessage 

DosQCurDir 

DosQCurDisk 

DosQFilelnfo 

DosQFileMode 

DosQSysInfo 

DosRead 

DosWrite 


The FSD may not call ANY FS helper routines at initialization time. 

Note that multiple code and data segments are not discarded by the loader as in 
the case of device drivers. 


The FSD may call DosGetlnfoSeg to obtain access to the global and process local 
information segments. The local segment may be used in the context of all proc- 
esses without further effort to make it accessible and has the same selector. The 
local infoseg is not valid in real mode or at interrupt time. 


OS/2 and DOS Extended Boot Structure and BIOS Parameter Block 

The Extended Boot structure is as follows: 

struct Extended_Boot { 
unsigned char Boot_jmp[3]; 

unsigned char Boot_OEM[8]; 

struct Extended_BPB Boot„BPB; 


unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 


Boot_DriveNumber; 

Boot_CurrentHead; 

Boot_Sig = 41; /Vindicate Extended Boot X 
Boot_Serial[4]; 

Boot_Vol_Label[l 1]; 

Boot_System_ID[8]; 


Where 

Serial is the 32-bit binary volume serial number for the media. 

SystemJD is an 8-byte name written when the media is formatted. It is used by 
FSDs to identify their media but need not be the same as the name 
the FSD exports via FS_NAME and is NOT the name users employ to 
refer to the FSD. (They may, however, be the same names). 
However, this name does need to match the FSD name used to 
create the U<fsdname>.DLL that contains the utilities. 
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VoLLabel is the 11-byte ASCII label of the disk/diskette volume. FAT file 

systems must ALWAYS use the volume label in the root directory for 
compatibility reasons. If at all possible, an FSD should use the 
volume label field in the boot sector. 

The extended BPB structure is a super-set of the conventional BPB structure, as 
follows: 

struct Extended_BPB { 
unsigned short BytePerSector; 

unsigned char SectorPerCluster; 

unsigned short ReservedSectors; 
unsigned char NumberOfFats; 

unsigned short RootEntries; 

unsigned short TotalSectors; 

unsigned char MediaDescriptor; 

unsigned short SectorsPerFat; 

unsigned short SectorsPerTrack; 

unsigned short Heads; 

unsigned long HiddenSectors; 

unsigned long Ext_TotalSectors; 

}; 
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IFS Commands 


IFS = (CONFIG.SYS Command) 

An FSD is loaded and initialized at system start-up when an IFS= statement is 
encountered in CONFIG.SYS. The syntax of this command is as follows: 

IFS=drive:path\name.ext parms 

where 

drive:path\name.ext specifies the FSD to load and initialize. 

parms represents an FSD-defined string of initialization param- 

eters. 

See the OS/2 Version 3.0 Online Command Reference for a detailed description of 
this command. 


File System Function Calls 

The OS/2 Version 3.0 Control Program Programming Reference gives a detailed 
description of the 32-bit file system calls new for OS/2 Version 3.0 See the OS/2 
Version 3.0 Programming Guide for a description of how to use these calls. For 
detailed descriptions of the 16-bit file system calls see the OS/2 Version 1.3 Control 
Program Programming Reference, and the OS/2 Version 1.3 Programming Guide 
on how to use these calls. 

Note: The data structures for some of the file system calls have changed in their 
32-bit implementaions. The kernel will handle all remapping between the 32-bit 
structures and the 16-bit structures used by individual FSDs. 

Application File I/O Notes 

File handle values of OxFFFF do not represent actual file handles but are used 
throughout the file system interface to indicate specific actions to be taken by the 
file system. Usage of this special file handle where it is not expected by the file 
system will result in an error. 

A 16 bit pointer is defined to be 000x:0000, where the least significant two bits in x 
is the ring number. Consequently, a ring 3 NULL pointer can be passed in as 
0003:0000. 

File systems that conform to the Standard Application Program Interface (Standard 
API) may not necessarily support all the described information kept on a file basis. 
When this is the case, FSDs are required to return to the application a null (zero) 
value for the unsupported parameter. 

An FSD may support version levels of files. 
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Date/Time Stamps 

The format of OS/2 dates are show below in Figure 1-5. 


Y|Y|Y|Y|Y|Y|Y|M|M|M|M|D|D|D|D|D| 
e|e|e|e|e|e|e|o|o|o|o|a|a|a|a|a| 
a|a|a|a|a|a|a|n|n|n|n|y|y|y|y|y| 
r I r | r | r | r | r | r | t | t | t | t | | I 

I I I I I I I h | h | h | h | | | | | | 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

Figure 1-5. OS/2 Date Format 


Bits Description 

15-9 YEARS - Number of years since 1980. 
8-5 MONTH - is the month of the year (1-12) 
4-0 DAY - is the day of the month (1-31) 


The format of OS/2 times are show below in Figure 1-6. 


H|H|H|H|H|M|M|M|M|M|M|2|2|2|2|2| 
o|o|o|o|o|i|i|i|i|i|i||||||||||| 
u|u|u|u|u|n|n|n|n|n|n|S|S|S|S|S| 
r I r | r | r | r | | | I |efe|e|e|e| 

I I I I I I I I I I I c I c I c I c I c I 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

Figure 1-6. OS/2 Time Format 


Bits Description 

15-9 HOUR - is the hour of the day (0-23) 

8-5 MINUTE - is the minute of the hour (0-59) 

4-0 2-SECOND - is the second of the minute(in increments of 2) (0-29) 


I/O Error Codes 

Some file system functions may return device-driver/device-manager generated 
errors. These include: 

ERROR_WRITE_PROTECT - the media in the drive has write-protection 
enabled. 

ERROR_BAD_UNIT - there is a breakdown of internal consistency between 
OS/2's mapping between logical drive and device driver. Internal Error. 

ERROR_NOT_READY - the device driver detected that the device is not ready. 

ERROR_BAD_COMMAND - there is a breakdown of internal consistency 
between OS/2's idea of the capability of a device driver and that of the device 
driver. 
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ERROFLCRC - the device driver has detected a CRC or ECC error. The data 
in the sector read has become corrupted and can not be corrected by the error 
correction code. 

ERROR_BAD_LENGTH - there is a breakdown of internal consistency between 
OS/2's idea of the length of a request packet and the device driver's idea of 
that length. Internal Error. 

ERROR_SEEK - the device driver detected an error during a seek operation. 

ERROR_NOT_DOS_DISK - the disk is not recognized as being OS/2 manage- 
able. 

ERROR_SECTOR_NOT_FOUND - the device is unable to find the specific 
sector. 

ERROR_OUT_OF_PAPER - the device driver has detected that the printer is 
out of paper. 

ERROR_WRITE_FAULT - other write-specific error. 

ERROR_READ_FAULT - other read-specific error. 

ERROR_GEN_FAILURE - other error. 

There are also errors defined by and specific to the device drivers. These are indi- 
cated by either OxFF or OxFE in the high byte of the error code. 

Note: Error codes listed in the function call descriptions in the OS/2 Version 3.0 
Control Program Programming Reference are not complete. They are errors most 
likely to be returned by the FS router and the FAT file system. Each FSD may 
generate errors based upon its own circumstances. Flowever, applications may be 
coded to expect the return codes to be limited to the ones in the documentation 
and may consequently fail, so it is wise to attempt to conform when possible. In 
addition, the error codes returned to FSJOCTL are restricted and may be modified 
before being returned to the user. For FSD specific requirements FS_FSCTL is 
recommended. 


FSD System Interfaces 
Overview 

Installable file system entry points are called by the kernel as a result of action 
taken through the published standard file I/O application programming interface in 
OS/2 Version 3.0. 

Installable file systems are installed as OS/2 dynamic link library modules. Unlike 
device drivers, they may include any number of segments, all of which will remain 
after initialization, unless the FSD itself takes some action to free them. 

An FSD exports FS entries to the OS/2 kernel using standard PUBLIC 
declaractions. Each FS entry is called directly. The OS/2 kernel manages the 
association between internal data structures and FSDs. 

When a file system service is required, OS/2 assembles an argument list, and calls 
the appropriate FS entry for the relevant FSD. If a back-level FSD is loaded, the 
OS/2 kernel assures that all arguments passed and all structures passed are 
understood by the FSD. 
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Application program interfaces that are unsupported by an FSD receive an UNSUP- 
PORTED FUNCTION error from the FSD. 

Certain routines, for example, FS_PROCESSNAME, may provide no processing, no 
processing is needed, or processing does not make sense. These routines return 
no error, not ERROR_NOT_SUPPORTED. 

Data Structures 

OS/2 data structures that include a pointer to the file system driver, as well as file 
system specific data areas are: 

the CDS (current directory structure) 
the SFT (system file table entry), 
the VPB (volume parameter block) 
the file search structures. 

File system service routines are generally passed pointers to two parameter areas, 
in addition to read-only parameters which are specific to each call. The FSD does 
not need to verify these pointers. The two parameter areas contain file-system- 
independent data which is maintained jointly by OS/2 and the file system driver and 
file-system-dependent data which is unused by OS/2 and which may be used by 
the file system driver. The file system driver is generally permitted to use the file- 
system- dependent information in any way: The file-system-dependent information 
may contain all the information needed to describe the current state of the file or 
directory, or it may contain a handle which will direct it to other information about 
the file maintained within the FSD. Flandles must be GDT selectors because any 
SFT, CDS, or VPB may be seen by more than one process. File-system- 
dependent and file-system-independent parameter areas are defined by data struc- 
tures described in the remainder of this section. 

Disk media and file system layout 

are described by the following structures. The data which is provided to 
the file system may depend on the level of file system support provided 
by the device driver attached to the block device. These structures are 
relevant only for local file systems. 

Afile system independent - volume parameters X 


struct vpfsi { 

unsigned long vpi_vid; A32-bit volume ID X 

unsigned long vpiJiDEV; //handle to the device driver X 

unsigned short vpi_bsize; Asector size in bytes X 

unsigned long vpi_totsec; Atotal number of sectors X 

unsigned short vpi_trksec; Asectors per track X 

unsigned short vpi_nhead; //number of heads X 

char vpi_text[12]; AASCIIZ volume name X 

void far / vpLpDCS; Adevice capability structure X 

void far / vpi_pVCS; Avolume characteristics X 

unsigned char vpi_drive; Adrive (0=A) X 

unsigned char vpLunit; Aunit code X 


unsigned short vpi_flags; Aflags for memory restrictions X 

}; 

AVPI_FLAGS Definitions: X 

#define VPB_NONCONTIG_ALLOWED 0x0002 Athe FSD for this volume can handle X 

Anon contig memory for IO requests. X 


Chapter 1. Installable File System Mechanism 1-19 



#define VPB_ABOVE 1 6M_ALLOWED 0x000 1 AThe DD for this volume can access X 

Aabove 1 6 M. X 


APredefined volume IDs: X 

AUnique ID for vpb_ID field for unreadable media. X 

#define UNREAD ID 0x534E4A52L AStored as (bytes) 0x52, 4A,4E, 53. X 

AUnique ID for vpb_ID field for damaged volume (recognized by IFS but X 
Acannot be normally mounted). X 

#define DAMAGED_ID 0x0L AStored as (bytes) 0, 0,0,0. X 


Afile system dependent - volume parameters X 
struct vpfsd { 

char vpi_work[36]; Awork area X 

}; 


Per-disk current directories 

are described by the following structures. These structures can only be 
modified by the FSD during FS_ATTACH and FS_CFIDIR operations. 

Afile system independent - current directories X 


struct cdfsi { 

unsigned short cdi_hVPB; AVPB handle for associated device X 

unsigned short cdi_end; Aoffset to root of path X 

char cdi_flags; AFS independent flags 

char cdi_curdir[260]; Atext of current directory X 

}; 


x 


Abit values for cdi_flags (state of cdfsd structure X 

#define CDI_ISVALID 0x80 Aformat is known X 

#define CDI_ISROOT 0x40 Acur dir == root X 

#define CDI_ISCURRENT 0x20 

Afile system dependent - current directories X 

struct cdfsd { 

char cdd_work[8]; Awork area X 

}; 


Open files 

are described by data initialized at file open time and discarded at the 
time of last close of all file handles which had been associated with that 
open instance of that file. There may be multiple open file references to 
the same file at any one time. 

All time stamps on files are stamped and propagated to other SFTs by 
OS/2 when the file is closed or committed (flushed). For example, if a 
file is opened at time 1, written at time 2, and closed at time 3, the last 
write time is time 3. 

Subdirectories need only have creation time stamps because the last 
write and last read time stamps on subdirectories are either very difficult 
to implement (propagate up to parent subdirectories), or are not very 
useful. An FSD, however, may implement them. 
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FSDs are required to support direct access opens. These are indicated 
by a bit set in the sffsi.sfijmode field. 

Afile system independent - file instance X 


struct sffsi { 


unsigned long sfLmode; 

Aaccess/sharing mode 

X 

unsigned short sfi_hVPB; 

Avolume info 


unsigned short sfi_ctime; 

Afile creation time 

X 

unsigned short sfi_cdate; 

Afile creation date 

X 

unsigned short sfi__atime; 

Afile access time 

X 

unsigned short sfi_adate; 

Afile access date 

X 

unsigned short sfi_mtime; 

Afile modification time 

X 

unsigned short sfi_mdate; 

Afile modification date 

X 

unsigned long sfi_size; 

Asize of file 

X 

unsigned long sfLposition; 

Aread/write pointer X 


Athe following may be of use 

in sharing checks X 


unsigned short sfLUID; 

Auser ID of initial opener 

X 

unsigned short sfLPID; 

Aprocess ID of initial opener 

X 

unsigned short sfLPDB; 

APDB (in 3x box of initial opener) 

X 

unsigned short sfi_selfsfn; 

Asystem file number of file instance X 


unsigned char sfi_tstamp; 

Atime stamps flag 


unsigned short sfLtype; 

Atype of object opened 

X 

unsigned long sfLpPVDBFil; Aperformance counter data block ptr 

X 

unsigned char sfLDOSattr; 

1 . 

ADOS file attributes D/S/A/H/R 

X 

Asfi_tstamps flags X 

#define ST_SCREAT 1 

Astamp creation time 


#define ST_PCREAT 2 

Apropagate creation time 


#defme STJSWRITE 4 

Astamp last write time 


#define ST_PWRITE 8 

Apropagate last write time 


#define ST_SREAD 16 

Astamp last read time 


#define ST_PREAD 32 

Apropagate last read time 


Asfi_type flags X 

#define STYPE_FILE 0 

Afile 


#define STYPE„DEVICE 1 

Adevice 


#define STYPEJNMPIPE 2 

Anamed pipe 


#define STYPE_FCB 4 

Afcb sft 



Afile system dependent - file instance X 
struct sffsd { 

char sfd_work[30]; Aworkarea X 

}; 


The Program Data Block, or PDB (sfi_pdb), is the unit of sharing for 
DOS mode processes. For OS/2 mode processes, the unit of sharing is 
the Process ID, PID (sfi_pid). 

FSDs should use the combination PDB, PID, UID as indicating a distinct 
process. 

File search records 

Afile system independent - file search parameters X 
struct fsfsi 

unsigned short fsi_hvpb; Avolume info X 

Afile system dependent - file search parameters X 
struct fsfsd 

char fsd_work[24] Awork area X 
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Note: The pointers to these structures are not guaranteed to be con- 
stant throughout their existance. The FSD should not keep internal 
pointers to these structures since the data may be moved. 

Existing file systems that conform to the Standard Application Program Interface 
(Standard API) described in this section, may not necessarily support all the 
described information kept on a file basis. When this is the case, file system 
drivers are required to return to the application a null (zero) value for the unsup- 
ported parameter (when the unsupported data are a subset of the data returned by 
the API) or to return a ERROR_NOT_SUPPORTED error (when all of the data 
returned by the API is unsupported). 

Time Stamping 

All time stamps on files are stamped and propagated to other SFTs when the file is 
closed or commited (flushed). If a file is opened at time 1, written to at time 2, and 
closed at time 3, the last write time will be time 3. Subdirectories only have cre- 
ation time stamps. 

The sfi_tstamp field of the file instance structure sffsi contains six flags: 


ST_SCREAT 

EQU 

1 

; stamp creation time 

ST_PCREAT 

EQU 

2 

; propagate creation time 

ST_SWRITE 

EQU 

4 

; stamp last write time 

ST_PWRITE 

EQU 

8 

; propagate last write time 

ST_SREAD 

EQU 

16 

; stamp last read time 

ST_PREAD 

EQU 

32 

; propagate last read time 


These flags are cleared when an SFT is created, and some of them may eventually 
be set by a file system worker routine. They are examined when the file is closed 
or flushed. 

For each time stamp, there are three meaningful actions: 


ST Sxxx 

ST„Pxxx 

Action 

clear 

clear 

don't do anything 

set 

set 

stamp and propagate (to other SFTs and disk) 

clear 

set 

don't stamp, but propagate existing value 


FSD Calling Conventions and Requirements 

Calling conventions between FS router, FSD, and FS helpers are: 

Arguments will be pushed in left-to-right order onto the stack. 

The callee is responsible for cleaning up the stack. 

Registers DS, SI, Dl, BP, SS, SP are preserved. 

Return conditions appear in AX with the convention that AX == 0 indicates suc- 
cessful completion. AX != 0 indicates an error with the value of AX being the 
error code. 

Interrupts must ALWAYS be enabled and the direction flag should be presumed to 
be undefined. Calls to the FS helpers will change the direction flag at will. 
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In OS/2, file system drivers are always called in kernel protect mode. This has the 
advantage of allowing the FSD to execute code without having to account for pre- 
emption; no preemption occurs when in kernel mode. While this greatly simplifies 
FSD structure, it forces the FSD to yield the CPU when executing long segments of 
code. In particular, an FSD must not hold the CPU for more than 2 milliseconds at 
a time. The FSD helper FSH_YIELD is provided so that FSDs may relinquish the 
CPU. 

File system drivers cannot have any interrupt-time activations. Because they 
occupy high, movable, and swappable memory, there is no guarantee of address- 
ability of the memory at interrupt time. 

Each FS service routine may block. 


Error Codes 

FSDs should use existing error codes when possible. New error codes must be in 
the range reserved for FSDs. The FS_FSCTL interface must support returning 
information about new error codes. Unfortunately, no current base applications 
support retrieving and displaying new error code information. Consequently, new 
error codes should be restricted to situations where they will only be returned to 
FSD aware programs. Hopefully in the future the extension of return codes will be 
supported by the user interface code. 


The set of error codes for errors general to all FSDs is OxEEOO - OxEEFF. The 
following errors have been defined: 

ERROR_VOLUME_NOT_MOUNTED = OxEEOO - the FSD did not recognize the 
volume. 

The set of error codes which are defined by each FSD is OxEFOO - OxFEFF. 
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Chapter 2. FS Service Routines 


The following table summarizes the entry points that make up the interface between 
the kernel and the FSD. 

Note: Names must be in all upper case, as required by OS/2 naming conventions. 


FS Entry Point 

Description 

FSDs Required to export 

FS^ALLOCATEPAGESPACE 

Adjust the size of paging file 

PAGE I/O 

FS_ATTACH 

Attach to an FSD 

ALL 

FS_CANCELLOCKREQUEST 

Cancel file record lock request 

FILE I/O 

FS_CHDIR 

Change/Verify directory path 

ALL 

FSJSHGFILEPTR 

Move a file's position pointer 

ALL 

FS„CLOSE 

Release a file handle 

ALL 

FSJSOMMIT 

Flush a file's buffer to disk 

ALL 

FS„COPY 

Copy a file 

ALL 

FS„DELETE 

Delete a file 

ALL 

FSJDOPAGEIO 

Perform paging I/O operations 

PAGE I/O 

FS_EXIT 

End of a process cleanup 

ALL 

FS_FILEATTRIBUTE 

Query/Set file's attributes 

ALL 

FSJRLEINFO 

Query/Set file's information 

ALL 

FS_FILEIO 

Multi-function file I/O 

FILE I/O 

FS„FILELOCKS 

Request a file record lock/unlock 

ALL 

FSJRNDCLOSE 

Directory search close 

ALL 

FSJRNDFIRST 

Find first matching filename 

ALL 

FSJRNDFROMNAME 

Find matching filename from name 

ALL 

FSJRNDNEXT 

Find next matching filename 

ALL 

FSJRNDNOTIFYCLOSE 

Close FindNotify handle 

ALL 

FSJRNDNOTIFYFIRST 

Monitor a directory for changes 

ALL 

FSJRNDNOTIFYNEXT 

Resume reporting directory changes 

ALL 

FS^FLUSHBUF 

Commit file buffers to disk 

ALL 

FS_FSCTL 

File system control 

ALL 

FS_FSINFO 

Query/Set file system information 

ALL 

FSJNIT 

FSD initialization 

ALL 

FSJOCTL 

I/O device control 

ALL 

FSJMKDIR 

Make a directory 

ALL 

FSJMOUNT 

Mount/unmount volumes 

ALL 

FSJMOVE 

Move a file or subdirectory 

ALL 

FSJNEWSIZE 

Change a file's logical size 

ALL 

FS_NMPIPE 

Do a named pipe operation 

ALL 

FSJDPENCREATE 

Open/create/replace files 

ALL 

FSJDPENPAGEFILE 

Create paging file and handle 

PAGE I/O 

FS^PATHINFO 

Query/Set a file's information 

ALL 

FS_PROCESSNAME 

FSD unique name canonicalization 

ALL 

FSJREAD 

Read data from a file 

ALL 

FS„RMDIR 

Remove a subdirectory 

ALL 

FS„SETSWAP 

Notification of swapfile ownership 

ALL 

FS^SHUTDOWN 

Shutdown file system 

ALL 

FS„VERIFYUNCNAME 

Verify UNC server ownership 

UNC 

FS_WRITE 

Write data to a file 

ALL 
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Each FS entry point has a distinct parameter list composed of those parameters 
needed by that particular entry. Parameters include: 

File pathname 

Current disk/directory information 

Open file information 

Application data buffers 

Descriptions of file extended attributes 

Other parameters specific to an individual call 

Most of the FS entry points have a level parameter for specifying the level of infor- 
mation they are provided or have to supply. FSDs must provide for additional 
levels which may be added in future versions of OS/2 by returning 
ERROR_NOT_SUPPORTED for any level they do not recognize. 


File system drivers which support hierarchical directory structures must use 'V and 
'/' as path name component separators. File system drivers which do not support 
hierarchical directory structures must reject as illegal any use of 'V or '/' in path 
names. The file names and are reserved for use in hierarchical directory 
structures for the current directory and the parent of the current directory, respec- 
tively. 

Unless otherwise specified in the descriptions below, data buffers may be accessed 
without concern for the accessibility of the data. OS/2 will either check buffers for 
accessability and lock them, or transfer them into locally accessible data areas. 

Simple parameters will be verified by the IFS router before the FS service routine is 
called. 

Note: New with 2.0, some entry points need only be exported and supported by 
those FSDs which desire to service the pager(PAGE I/O), UNC servers(UNC) 
and/or file locking(FILE I/O). With these new entry point groups, a FSD must 
export all or none of the entry points within a particular group. 


These optional entry points are: 

FS_AllocatePageSpace (PAGE I/O) 
FS_CancelLockRequest (FILE I/O) 


FS_DoPagelO 

FS_FileLocks 

FS_OpenPageFile 

FS_VerifyUNCName 


(PAGE I/O) 
(FILE I/O) 
(PAGE I/O) 
(UNC) 
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FS_ALLOCATEPAGESPACE 
Adjust the size of paging file 

Purpose 

Changes the size the paging file on disk. 

Calling Sequence 

int far pascal FS_ALLOCATEPAGESPACE (psffsi, psffsd, ulsize, 

ulWantContig) 


struct sffsi far \ psffsi; 
struct sffsd far \ psffsd; 
unsigned long ulsize; 

unsigned long ulWantContig; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

ulsize 

is the desired new size of the paging file. If the new size is smaller than the 
current size, the excess space is released. If the new size is larger than the 
current size, the requested size is allocated. 

ulWantContig 

indicates the mimimum contiguity requirement (in bytes). 

Remarks 

ulWantContig is a demand for contiguity. If ulWantContig is non-zero(O), the FSD 
must allocate any space in the swap file that is not contigous in ulWantContig 
chunks on ulWantContig boundaries. If it is not possible to grow the file to ulSize 
bytes meeting the ulWantContig requirement, the operation should fail. If the file is 
being shrunk ulWantContig is irrelevent and should be ignored. 

FSDs that support the paging I/O interface should be expected to be sensible in 
allocating page space. In particular, they are expected to always attempt to allocate 
space such that ulWantContig sized blocks on ulWantContig boundaries are phys- 
ically contigous on disk, and to keep the page file as a whole contigous as pos- 
sible. 
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FS_ATTACH 
Attach to an FSD 

Purpose 

Attach or detach a remote drive or pseudo-device to an FSD. 

Calling Sequence 

int far pascal FS_ATTACH (flag, pDev, pvpfsd, pcdfsd, pPann, pLen) 

unsigned short flag; 

char far \ pDev; 

struct vpfsd far \ pvpfsd; 

struct cdfsd far \ pcdfsd; 

char far \ pParm; 

unsigned short far \ pLen; 


Where 

flag 

indicates attach or detach: 

flag == FSA_ATTACH (0x00) requests an attach. The FSD is being called 
to attach a specified driver or character device, 
flag == FSA_DETACFI (0x01) requests a detach. 

flag == FSA_ATTACH_INFO (0x02) requests the FSD to fill in the specified 
buffer with attachment information. 


pDev 

is a pointer to the ASCIIZ text of either the driver (driver letter followed by a 
colon) or to the character device (must be \DEV\device) that is being attached, 
detached, or queried. The FSD does not need to verify this pointer. 

pvpfsd 

is a pointer to a data structure containing file-system-dependent volume param- 
eter information. When an attach/detach/query of a character device is 
requested, this pointer is null. When attaching a drive, this structure contains no 
data and is available for the FSD to store information needed to manage the 
remote drive. All subsequent FSD calls have access to the hVPB in one of the 
structures passed in, so the FSD has access to this structure by using 
FSH_GETVOLPARMS. This structure will have its contents as the FSD had left 
them. When detaching or querying a drive, this structure contains the data as 
the FSD left them. 

pcdfsd 

is a pointer to a data structure containing file-system dependent working direc- 
tory information for drives. When attaching a drive, this structure contains no 
data and is available for the FSD to store information needed to manage the 
working directory. All subsequent FSD calls generated by API calls that refer- 
ence this drive are passed a pointer to this structure with contents left as the 
FSD left them. When detaching or querying a drive, this structure contains the 
data as the FSD left them. For character devices, pcdfsd points to a DWORD. 
When a device is attached, the DWORD contains no data, and can be used by 
the FSD to store a reference to identify the device later on during 
FS_OPENCREATE, when it is passed in to the FSD. When detaching or que- 
rying the device, this DWORD contains the data as the FSD left them. 
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When the FSD is notified of a detach, it should deallocate any resources allo- 
cated for this structure. 

Note: The FSD should not expect this pointer to remain constant for the dura- 
tion of the attach. The contents of the structure will be valid, but the location 
may change. 

pParm 

is the address of the application parameter area. 

When an attach is requested, this will point to the API-specified user data block 
that contains information regarding the attach operation (for example, pass- 
words). For a query, the OS/2 kernel will fill in part of the buffer, adjust the 
pointer, and call the FSD to fill in the rest. (See structure returned by 
DosQFSAttach; pParm will point to cbFSAData; the FSD should fill in 
cbFSAData and rgFSAData.) 

Addressing of this data area is not validated by the OS/2 kernel. pParm must 
be verified, even in the query case. The FSD verifies this parameter by calling 
the FS helper routine FSFI_PROBEBUF. 

pLen 

is the pointer to the length of the application parameter area. 

For attach, this points to the length of the application data buffer. For query, 
this is the length of the remaining space in the application data buffer. Upon 
filling in the buffer, the FSD will set this to the length of the data returned. If the 
data returned is longer than the data buffer length, the FSD sets this value to be 
the length of the data that query could return. In this case, the FSD should also 
return a BUFFER OVERFLOW error. 

The FSD does not need to verify this pointer. 

Remarks 

Local FSDs will never get called with attempts to attach, detach or query drives. 

For remote FSDs called to do a detach, the kernel does not do any checking to see 
if there are any open references on the drive (for example, open or search refer- 
ences). It is entirely up to the FSD to decide whether it should allow the detach 
operation. 
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FS_CANCELLOCKREQUEST 
Cancel file record lock request 

Purpose 

Cancels an outstanding FS_FileLocks request on a file. 

Calling Sequence 

int far pascal FS_CANCELLOCKREQUEST (psffsi, psffsd, pLockRange) 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

stiuct filelock far \ pLockRange; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pLockRange 

is a pointer to a filelock structure. The filelock structure has the following format: 

struct FileLock { 

unsigned long FileOffset; Aoffset where the lock/unlock begins X 
unsigned long RangeLength; Alength of region locked/unlocked X 

} 


Remarks 

This entry point was added to support the 32-bit DosCancelLockRequest API. 

This function provides a simple mechanism for cancelling the lock range request of 
an outstanding FS_FILELOCKS call. If two threads in a process are blocked on a 
lock range and a cancel request is issued by another thread, both blocked threads 
will be released. 
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FS_CHDIR 

Change/Verify Directory Path 


Purpose 

Change or verify the directory path for the requesting process 

Calling Sequence 

int far pascal FS_CHDIR (flag, pcdfsi, pcdfsd, pDir, iCurDirEnd) 

unsigned short flag; 

struct cdsfi far \ pcdfsi; 

struct cdfsd far \ pcdfsd; 

char far \ pDir; 

unsigned short iCurDirEnd; 


Where 

flag 

indicates what action is to be taken on the directory. 

flag == CD_EXPLICIT (0x00) indicates that an explicit directory-change 
request has been made. 

flag == CD_VERIFY (0x01) indicates that the working directory needs to be 
verified. 

flag == CD_FREE (0x02) indicates that this reference to a directory is being 
freed. 

The flag passed to the FSD will have a valid value. 

pcdfsi 

is a pointer to a file-system-independent working directory structure. 

For flag == 0, this pointer points to the previous current directory on the 
drive. 

For flag == 1, this pointer points to the most-recent working directory on the 
drive. The cdi_curdir field contains the text of the directory that is to be 
verified. 

For flag == 2, this pointer is null. 

The FSD must never modify the cdfsi. The OS/2 kernel handles all updates. 

pcdfsd 

is a pointer to a file-system-dependent working directory structure. 

This is a place for the FSD to store information about the working directory. 

The FSD is expected to update this information if the directory exists. The 
cdfsd pointer is always valid upon entry. If the current directory is the root 
directory, the contents of this area is undefined. Otherwise, the information is 
the information that was left there by the FSD. 

pDir 

is a pointer to directory text. 

For flag == 0, this is the pointer to the directory. For flag == 1 or flag == 2, this 
pointer is null. The FSD does not need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pDir. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
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current directory relevant to the directory text, that is, a device. This parameter 
only has meaning for flag == 0. 

Remarks 

The FSD should cache no information when the directory is the root. Root directo- 
ries are a special case. They always exist, and never need validation. The OS/2 
kernel does not pass root directory requests to the FSD. An FSD is not allowed to 
cache any information in the cdfsd data structure for a root directory. Under normal 
conditions, the kernel does not save the CDS for a root directory and builds one 
from scratch when it is needed. (One exception is where a validate CDS fails, and 
the kernel sets it to the root, and zeroes out the cdfsd data structure. This CDS is 
saved and is cleaned up later.) 

The following is information about the exact state of the cdfsi and cdfsd data struc- 
tures passed to the FSD for each flag value and guidelines about what an FSD 
should do upon receiving an FS_CFIDIR call: 

IF ( flag == 0) ASet new Current Directory X 

pcdfsi, pcdfsd = copy of CDS we're starting from; may be useful as starting 
point for verification. 

cdfsi contents: 

hVPB - handle of Volume Parameter Block mapped to this drive 

end - end of root portion of CurDir 

flags - various flags (indicating state of cdfsd) 

IsValid - cdfsd is unknown format (ignore contents) 

IsValid == 0x80 


IsRoot - cdfsd is meaningless if CurDir = root (not kept) 
IsRoot == 0x40 


IsCurrent - cdfsd is know format, but may not be current (medium 
may have been changed). 

IsCurrent == 0x20 

text - Current Directory Text 

icurdir = if Current Directory is in the path of the new Current Directory, 
this is the index to the end of the Current Directory. If not, 
this is -1 (Current Directory does not apply). 

pDir = path to verify as legal directoiy 

THEN 

Validate path named in pDir. 

AThis means both that it exists AND that it is a directory, pcdfsi, 
pcdfsd, icurdir give old CDS, which may allow optimization X 

IF (Validate succeeds) 

IF (pDir != ROOT) 

Store any cache information in area pointed to by pcdfsd. 

ELSE 

Do Nothing. 

AArea pointed to by pcdfsd will be thrown away, so don't bother 
storing into it X 
Return success. 
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ELSE 

Return failure. 

AKemel will create new CDS using pDir data and pcdfsd data. If the 
old CDS is valid, the kernel will take care of cleaning it up. The 
FSD must not edit any structure other than the Pcdfsd area, with 
which it may do as it chooses. X 
Mag == 0 X 
ELSE 

IF (flag == 1) AValidate current CDS structure X 


pcdfsi = pointer to copy of cdfsi of interest. 


pcdfsd = pointer to copy of cdfsd. Flags in cdfsi indicate the state of 
this cdfsd. It may be: (1) completely invalid (unknown 
format), (2) known format, but non-current information, 

(3) completely valid, or (4) all zero (root). 


THEN 

Validate that CDS still describes a legal directory (using cdi_text). 

IF (valid) 

Update cdfsd if necessary. 

Return success. 

Akernel will copy cdfsd into real CDS X 
ELSE 

IF (cdi_isvalid) 

Release any resources associated with cdfsd. 

Akernel will force Current Directory to root, and will zero out 
cdfsd in real CDS X 
Return failure. 

AThe FSD must not modify any structure other than the cdfsd pointed to by 
pcdfsd. X 

ELSE 

IF (flag == 2) Aprevious CDS no longer in use; being freed X 
pcdfsd = pointer to copy of cdfsd of CDS being freed. 

THEN 

Release any resources associated with the CDS. 

AFor example, if cdfsd (where pcdfsd points) contains a pointer to 
some FSD private structure associated with the CDS, that structure 
should be freed. X 

/Xkernel will not retain the cdfsd X 
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FS_CHGFILEPTR 

Move a file's position pointer 


Purpose 

Move a file's logical read/write position pointer. 

Calling Sequence 

int far pascal FS_CHGFILEPTR ( psffsi, psffsd, offset, type, IOflag ) 


struct ssfsi far \ 
struct ssfsd far \ 
long 

unsigned short 
unsigned short 


psffsi; 

psffsd; 

offset; 

type; 

IOflag; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

The FSD uses the current file size or sfi_position along with offset and type to 
compute a new sfLposition. This is updated by the system. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

The FSD may store or adjust data as appropriate in this structure. 

offset 

is the signed offset to be added to the current file size or position to form the 
new position within the file. 

type 

indicates the basis of a seek operation. 

type == CFP_RELBEGIN (0x00) indicates seek relative to beginning of file, 
type == CFP_RELCUR (0x01) indicates seek relative to current position 
within the file. 

type == CFP_RELEND (0x02) indicates seek relative to end of file. 

The value of type passed to the FSD will be valid. 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 

IOflag == IOFL_NOCACHE (0x0020) indicates no-cache. 

Remarks 

The file system may want to take the seek operation as a hint that an I/O operation 
is about to take place at the new position and initiate a positioning operation on 
sequential access media or read-ahead operation on other media. 

Some DOS mode programs expect to be able to do a negative seek. OS/2 passes 
these requests on to the FSD and returns an error for OS/2 mode negative seek 
requests. Because a seek to a negative position is, effectively, a seek to a very 
large offset, it is suggested that the FSD return end-of-file for subsequent read 
requests. 
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FSDs must allow seeks to positions beyond end-of-file. 


The information passed in lOflag is what was set for the handle during a 
DosOpen/DosOpen2 operation, or by a DosSetFHandState call. 

If an FSD supports file locking, it is responsible for checking if there are any locks 
on the file that should prevent the call from being executed. OS/2 will not do any 
lock checking if the FSA_LOCK bit is set in the FSD Attributes. 
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FS_CLOSE 
Close a file. 


Purpose 

Closes the specified file handle. 

Calling Sequence 

int far pascal FS_CLOSE (type, IOflag, psffsi, psffsd) 

unsigned short type; 

unsigned short IOflag; 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 


Where 

type 

indicates what type of a close operation this is. 

type == FS_CL_ORDINARY (0x00) indicates that this is not the final close 
of the file or device. 

type == FS_CL_FORPROC (0x01) indicates that this is the final close of this 
file or device for this process. 

type == FS_CL_FORSYS (0x02) indicates that this is the final close for this 
file or device for the system. 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 

IOflag == IOFL_NOCACFIE (0x0020) indicates no-cache. 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

Remarks 

This entry point is called on every close of a file or device. 

Any reserved resources for this instance of the open file may be released. It may 
be assumed that all open files will be closed at process termination. That is, this 
entry point will always be called at process termination for any files or devices open 
for the process. 

A close operation should be interpreted by the FSD as meaning that the file should 
be commited to disk as appropriate. 

Of the information passed in IOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the FSD 
returns. The no-cache bit, on the other hand, is an advisory bit that says whether 
the data being transferred is worth caching or not. 
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FS_COMMIT 

Commit a file's buffers to Disk 

Purpose 

Flush requesting process's cache buffers and update directory information for the 
file handle. 

Calling Sequence 

int far pascal FS_COMMIT (type, IOflag, psffsi, psffsd) 

unsigned short type; 

unsigned short IOflag; 

struct sffsi far \ psffsi; 
struct sffsd far\ psffsd; 


Where 

type 

indicates what type of a commit operation this is. 

type == FS_COMMIT_ONE (0x01) indicates that this is a commit for a spe- 
cific handle. This type is specified if FS_COMMIT is called for a 
DosBufReset of a specific handle. 

type == FS_COMMIT_ALL (0x02) indicates that this is a commit due to a 
DosBufReset (-1). 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 

IOflag == IOFL_NOCACHE (0x0020) indicates no-cache. 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

Remarks 

This entry point is called only as a result of a DosBufReset function call. OS/2 
reserves the right to call FS_COMMIT even if no changes have been made to the 
file. 

For DosBufReset (-1), FS_COMMIT will be called for each open handle on the 
FSD. 

The FSD should update access and modification times, if appropriate. 

Any locally cached information about the file must be output to the media. The 
directory entry for the file is to be updated from the sffsi and sffsd data structures. 

Since mini-FSDs used to boot IFSs are read-only file systems, they need not 
support the FS_COMMIT call. 

Of the information passed in IOflag, the write-through bit is a MANDATORY bit in 
that any data written to the block device must be put out on the medium before the 
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FSD returns. The no-cache bit, on the other hand, is an advisory bit that says 
whether the data being transferred is worth caching or not. 

The FSD should copy all supported time stamps from the SFT to the disk. Beware 
that the last read time stamp may need to be written to the disk even though the 
file is clean. After this is done, the FSD should clear the sfijstamp field to avoid 
having to write to the disk again if the user calls commit repeatedly without 
changing any of the time stamps. 

If the disk is not writeable and only the last read time stamp has changed, the FSD 
should either issue a warning or ignore the error. This relieves the user from 
having to un-protect an FSD floppy disk in order to read the files on it. 
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FS_COPY 
Copy a file 


Purpose 

Copy a specified file or subdirectory to a specified target. 

Calling Sequence 

int far pascal FS_COPY ( flag, pcdfsi, pcdfsd, 

pSrc, iSrcCurDirEnd, 
pDst, iDstCurDirEnd, 
nameType) 

unsigned short flag; 

struct cdfsi far \ pcdfsi; 

struct cdfsd far \ pcdfsd; 

char far \ pSrc; 

unsigned short iSrcCurDirEnd; 
char far \ pDst; 

unsigned short iDstCurDirEnd; 
unsigned short nameType; 


Where 

flag 

is a bit mask controlling copy 

0x0001 specifies that an existing target file/directory should be replaced 
0x0002 specifies that a source file will be appended to the destination file. 
All other bits are reserved. 

(See the description of the DosCopy function call in the OS/2 Version 3.0 
Control Program Programming Reference.) 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependeng working directory structure. 

pSrc 

is a pointer to the ASCIIZ name of the source file/directory. 

iSrcCurDirEnd 

is the index of the end of the current directory in pSrc. If = -1, there is no 
current directory relevant to the source name. 

pDst 

is a pointer to the ASCIIZ name of the destination file/directory. 

iDstCurDirEnd 

is the index of the end of the current directory in pDst. If = -1, there is no 
current directory relevant to the destination name. 

nameType 

indicates the destination name type. 

NameType == 0x0040 indicates non-8.3 filename format. All other values are 
reserved. 
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Remarks 

The file specified in the source file name should be copied to the target file if pos- 
sible. 

The files specified may not be currently open. File system drivers must assure 
consistency of file allocation information and directory entries. 

The file system driver returns the special CANNOT COPY error if it cannot perform 
the copy because: 

it does not know how 

the source and target are on different volumes 

of any other reason for which it would make sense for its caller to perform the 
copy operation manually. 

Returning ERROR_CANNOT_COPY indicates to its caller that it should attempt to 
perform the copy operation manually. Any other error will be returned directly to 
the caller of DosCopy. Currently, the manual copy is performed in the 
DOSCALL1 .DLL if ERROR_CANNOT_COPY is returned. Although support of this 
functions is not required beyond the return code of ERROR_CANNOT_COPY, it is 
encouraged due to the significant performance improvement copying within the 
FSD. See the description of the DosCopy function call in the OS/2 Version 3.0 
Control Program Programming Reference for other error codes that can be 
returned. 

FS_COPY needs to check that certain types of illegal copying operations are not 
performed. A directory cannot be copied to itself or to one of its subdirectories. 
This is especially critical in situations where two different fully-qualified pathnames 
can refer to the same file or directory. For example, if X: is redirected to 
\\SERVER\SHARE, the X:\PATH and \\SERVER\SHARE\PATH refer to the same 
object. 

The behavior of FS_COPY should match the behavior of the generic DosCopy 
routine. 

The non-8.3 filename format attribute in the directory entry for the destination name 
should be set according to the value in nameType. 
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FS_DELETE 
Delete a file 


Purpose 

Removes a directory entry associated with a filename. 

Calling Sequence 

int far pascal FS_DELETE (pcdfsi, pcdfsd, pFile, iCurDirEnd) 

struct cdfsi far \ pcdfsi; 

struct cdfsd far \ pcdfsd; 

char far \ pFile; 

unsigned short iCurDirEnd; 

Where 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pFile 

is a pointer to the ASCIIZ name of the file or directory. The FSD does not need 
to validate this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pFile. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
current directory relevant to the name text, that is, a device. 

Remarks 

The file specified is deleted. 

The deletion of a file opened in DOS mode by the same process requesting the 
delete is supported. OS/2 calls FS_CLOSE for the file before calling FS_DELETE. 

The file name may not contain wildcard characters. 
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FS_DOPAGEIO 

Perform paging I/O operations 


Purpose 

Performs all the I/O operations in a PageCmdList. 

Calling Sequence 

int far pascal FS_DOPAGIO (psffsi, psffsd, pList) 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

struct PageCmdHeader far \ pList; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pList 

is a pointer to a PageCmdHeader structure. The PageCmdHeader structure has 
the following format: 


struct PageCmdHeader { 

unsigned char InFlags; //Input Flags X 

unsigned char OutFlags; AOutput Flags - must be 0 on entry X 
unsigned char OpCount; //Number of operations X 

unsigned char Pad; APad for DWORD alignment X 

unsigned long Reservedl; ACurrently Unused X 

unsigned long Reserved2; ACurrently Unused X 

unsigned long Reserved3; ACurrently Unused X 

struct PageCmd PageCmdList; ACurrently Unused X 


} 

AFSDJDoPagelO InFlags values X 
#define PGIO„FI_ORDER 0x01 

AFSD_DoPageIO OutFlags values X 
#define PGIO_FOJDONE 0x01 
#define PGIO_FO_ERROR 0x02 

AFSD_DoPageIO Status values X 
#define PGIO_ATTEMPTED 0x0f 
#defme PGIO_F AILED 0xfD 


//Force Order of operations X 

A Operation done X 

AOperation failed X 

AOperation attempted X 

AOperation failed X 


The PageCmd structure has the following format: 

struct PageCmd { 

X 

X 
X 

} 


unsigned char Cmd; ACmd Code (Read, Write, Verify) 

unsigned char Priority; ASame values as for req packets X 

unsigned char Status; AStatus byte 

unsigned char Error; AI24 error code 

unsigned long Addr; APhysical(0:32) or Virtual(16:16) X 

unsigned long FileOffset; //Byte Offset in page file X 
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Remarks 

FS_DOPAGEIO performs all the I/O operations specified in the PageCmdList. 

If the disk driver supports Extended Strategy requests, a request list will be built 
from the PageCmdList and issued to the driver. 

If the disk driver does not support Extended Strategy requests, the FSD can either 
let the kernel do the emulation(See FS_OPENPAGEFILE to set this state) or has 
the option to do the emulation itself. 

For a detailed description of the Extended Strategy request interface please see the 
OS/2 Version 3.0 Physical Device Driver Reference. 
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FS_EXIT 
End of process 


Purpose 

Release FSD resources still held after process termination. 

Calling Sequence 

void far pascal FS_EXIT (uid, pid, pdb); 

unsigned short uid; 

unsigned short pid; 

unsigned short pdb; 


Where 

uid 

is the user ID of the process. This will be a valid value. 

pid 

is the process ID of the process. This will be a valid value. 

pdb 

is the DOS mode process ID of the process. This will be a valid value. 

Remarks 

Because all files are closed when a process terminates, this call is not needed to 
release file resources. It is, however, useful if resources are being held due to 
unterminated searches (as in searches initiated from the DOS mode). If an FSD 
allocates resources every time an FS_FINDFIRST sequence is entered, resource 
shortages can occur under DOS since DOS programs do not have a DosFindClose 
API. This entry point provides a way for an FSD to determine that those resources 
may be released. 
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FS_FILE ATTRIBUTE 
Query/Set File Attribute 

Purpose 

Query/Set the attribute of the specified file. 

Calling Sequence 

int far pascal FS_FILE ATTRIBUTE (flag, pcdfsi, pcdfsd, 

pName, iCurDirEnd, pAttr) 


unsigned short 
struct cdfsi far \ 
struct cdfsd far \ 
char far \ 
unsigned short 
unsigned short far \ 


flag; 


pcdfsi; 

pcdfsd; 

pName; 

iCurDirEnd; 

pAttr; 


Where 

flag 

indicates retrieval or setting of attributes, with: 

flag == FA_RETRIEVE (0x00) indicates retrieving the attribute, 
flag == FA_SET (0x01) indicates setting the attribute, 
flag == all other values, reserved. 

The value of flag passed to the FSD will be valid. 

pcdfsi 

is a pointer to the file-system independent portion of an open file instance. 

pcdfsd 

is a pointer to the file-system dependent portion of an open file instance. 

pName 

is a pointer to the ASCIIZ name of the file or directory. 

The FSD does not need to validate this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
current directory relevant to the name text, that is, a device. 

pAttr 

is a pointer to the attribute. 

For flag == 0 (Query), the FSD should store the attribute in the indicated 
location. 

For flag == 1 (Set), the FSD should retrieve the attribute from this location 
and set it in the file or directory. 

The FSD does not need to validate this pointer. 
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Remarks 

None 
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FS_FILEINFO 

Query/Set a File's Information 


Purpose 

Returns information for a specific file. 

Calling Sequence 

int far pascal FS_FILEINFO (flag, psffsi, psffsd, 

level, pData, cbData, IOflag) 


unsigned short 

flag; 

struct sffsi far \ 

psffsi; 

struct sffsd far \ 

psffsd; 

unsigned short 

level; 

char far \ 

pData; 

unsigned short 

cbData: 

unsigned short 

IOflag; 

Where 


flag 



indicates retrieval or setting of information. 

flag == FI_RETRIEVE (0x00) indicates retrieving information, 
flag == FI_SET (0x01) indicates setting information. 

All other values are reserved. 

The value of flag passed to the FSD will be valid. 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

level 

is the information level to be returned. 

Level selects among a series of data structures to be returned. 

pData 

is the address of the application data area. 

Addressing of this data area is validated by the kernel (see FSH_PROBEBUF). 

When retrieval (flag == 0) is specified, the FSD will place the information 
into the buffer. 

When outputting information to a file (flag == 1), the FSD will retrieve that 
data from the application buffer. 

cbData 

is the length of the application data area. 

For flag == 0, this is the length of the data the application wishes to retrieve. 
If there is not enough room for the entire level of data to be returned, the 
FSD will return a BUFFER OVERFLOW error. 

For flag == 1, this is the length of data to be applied to the file. 
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lOflag 

indicates information about the operation on the handle. 

lOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 
lOflag == IOFL_NOCACHE (0x0020) indicates no-cache. 

Remarks 

If setting the time/date/DOS attributes on a file: 

Copy the new time/date/DOS attributes into the SFT 
Set ST_PCREAT, ST_PWRITE, and ST_PREAD 
Clear ST_SCREAT, ST_SWRITE, and ST_SREAD 
Do not change the file size with this entry point. 

Note: ALSO NEW FOR 2.0, it is suggested that the FSD copy the DOS file attri- 
butes from the directory entry into the SFT. This allows the FSD and the OS2 
kernel to handle FCB opens more efficently. 

If querying the date/time/DOS attributes on a file, simply copy the date/time/DOS 
attributes from the directory entry into the SFT. 

If the attribute value for the date or time is 0 (zero), you should not change the 
current value, as per the OS/2 Version 3.0 Control Program Programming Refer- 
ence. 

Of the information passed in lOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the 
device driver returns. The no-cache bit, on the other hand, is an advisory bit that 
says whether the data being transferred is worth caching or not. 

Supported information levels are described in the OS/2 Version 3.0 Control 
Program Programming Reference. However, since the IFS architecture is still 16 
Bit, the data structures that the FSD returns are the structures GEA, GEALIST, 

FEA, FEALIST, and EAOP- not the GEA2, GEA2LIST, etc. (see below). OS/2 will 
convert the structure to the appropriate 32 Bit form for 32 Bit applications. In addi- 
tion to the information levels described in the OS/2 Version 3.0 Control Program 
Programming Reference level 4 support is required in all FSDs. For level 4, ignore 
the GEALIST and return all EAs to the caller in the FEALIST. The external publica- 
tion of level 4 for 32 bit applications is being considered at this time. This call will 
not be officially supported for 16 Bit applications since we are hoping in the future 
to permit extended attributes to exceed 64K and that would break those applica- 
tions. 
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typedef struct _GEA { Agea X 

BYTE cbName; A name length not including NULL 

CHAR szName[l]; A attribute name 

} GEA; 


typedef struct _GEALIST { Ageal X 

ULONG cbList; Atotal bytes of structure inc full list X 

GEA list[ 1 ]; A variable length GEA structures 

} GEALIST; 


typedef struct _FEA { 
BYTE fEA; 
BYTE cbName; 
USHORT cbValue; 
} FEA; 

typedef FEA FAR PFEA; 
Aflags for _FEA.fEA X 


Afea X 
A flags 

A name length not including NULL 
Avalue length 


#define FEA_NEEDEA 0x80 


Aneed EA bit X 


X 


X 


X 

X 

X 


typedef struct _FEALIST { 
ULONG cbList; 
FEA list[l]; 

} FEALIST; 


Afeal X 

Atotal bytes of structure inc full list X 
A variable length FEA structures X 


typedef struct _EAOP { 

PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


Aeaop X 

Ageneral EA list X 
Afull EA list X 


Application Note: When an application does a level 3 query, it supplies a list of 
EA names in the GEALIST that they want the EA values for. If there are no 
extended attributes for that file, it is legal to return an FEALIST with a cbList equal 
to 4 and no FEAs. Flowever, there have been applications in the past that have 
coded assuming that an FEALIST will be returned with a cbValue of 0 if the EA 
does not exist. If those applications try to access the non-initialized information 
they will, of course, fail. FSD implementors may avoid future problems by returning 
the FEALIST with cbValues set to 0 when there are no EAs, but this is not an 
architectural requirement. 
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FS_FILEIO 

Multi-function file I/O 


Purpose 

Perform multiple lock, unlock, seek, read, and write I/O. 

Calling Sequence 

int far pascal FS_FILEIO (psffsi, psffsd, 

pCmdList, cbCmdList, poError, IOflag) 


struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

char far \ pCmdList; 

unsigned short cbCmdList; 

unsigned short far \ poError; 
unsigned short IOflag; 

Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pCmdList 

is a pointer to a command list that contains entries indicating what commands 
will be performed. 

Each individual operation (CmdLock, CmdUnloc, CmdSeek, CmdIO) is per- 
formed as atomic operations until all are complete or until one fails. CmdLock 
executes a multiple range lock as an atomic operation. CmdUnlock executes a 
multiple range unlock as an atomic operation. Unlike CmdLock, CmdUnlock 
cannot fail as long as the parameters to it are correct, and the calling application 
had done a Lock earlier, so it can be viewed as atomic. 

The validity of the user address is not verified (see FSH_PROBEBUF). 

For CmdLock, the command format is: 


struct CmdLock { 

unsigned short Cmd = 0; AO for lock operations X 

unsigned short LockCnt; //number of locks that follow X 

unsigned long TimeOut; Ams timeout for lock success X 

} 

which is followed by a series of records of the following format: 

struct Lock { 
unsigned short Share = 0; 
long Start; 

long Length; 

} 

If a lock within a CmdLock causes a timeout, none of the other locks within 
the scope of CmdLock are in force, because the lock operation is viewed as 
atomic. 

CmdLock.TimeOut is the count in milliseconds, until the requesting process 
is to resume execution if the requested locks are not available. If 


A0 for exclusive, 1 for read-only X 
Astart of lock region X 

//length of lock region X 
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CmdLock.TimeOut == 0, there will be no wait. If CmdLock.TimeOut < 
OxFFFFFFFF it is the number of milliseconds to wait until the requested 
locks become available. If CmdLock.TimeOut == OxFFFFFFFF then the 
thread will wait indefinitely until the requested locks become available. 

Lock.Share defines the type of access other processes may have to the file- 
range being locked. If its value == 0, other processes have No-Access to 
the locked range. If its value == 1 , other process have Read-Only access to 
the locked range. 

For CmdUnlock, the command format is: 


struct CmdUnlock { 

unsigned short Cmd = 1; A 1 for unlock operations X 

unsigned short UnlockCnt; A Number of unlocks that follow X 

} 

which is followed by a series of records of the following format: 

struct UnLock { 

long Start; Astart of locked region X 

long Length; Alength of locked region X 

} 

For CmdSeek, the command format is: 


struct CmdSeek { 

unsigned short Cmd = 2; A 2 for seek operation X 

unsigned short Method; A 0 for absolute X 

A 1 for relative to current X 
A 2 for relative to EOF X 


long Position; A file seek position or delta X 

long Actual; A actual position seeked to X 

} 

For CmdIO, the command format is: 


struct CmdIO { 
unsigned short Cmd; 
void far \ Buffer; 
unsigned short BufferLen; 
unsigned short Actual; 

} 


A 3 for read, 4 for write X 
A pointer to the data buffer X 
A number of bytes requested X 
A number of bytes transferred X 


cbCmdList 

is the length in bytes of the command list. 

poError 

is the offset within the command list of the command that caused the error. 
This field has a value only when an error occurs. 

The validity of the user address has not been verified (see FSH_PROBEBUF). 

lOflag 

indicates information about the operation on the handle. 

lOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 
lOflag == IOFL_NOCACHE (0x0020) indicates no-cache. 
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Remarks 

This function provides a simple mechanism for combining the file I/O operations 
into a single request and providing improved performance, particularly in a net- 
working environment. 

File systems that do not have the FilelO bit in their attribute field do not see this 
call: The command list is parsed by the IFS router. The FSD sees only 
FS_CHGFILEPTR, FS_READ, FS_WRITE calls. 

File systems that have the FilelO bit in their attribute field see this call in its 
entirety. The atomicity guarantee applies only to the commands themselves and 
not to the list as a whole. 

Of the information passed in lOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the 
device driver returns. The no-cache bit, on the other hand, is an advisory bit that 
says whether the data being transferred is worth caching or not. 
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FS_FILELOCKS 

Request a file record lock/unlock 

Purpose 

Locks and/or unlocks a range(record) in a opened file. 

Calling Sequence 

int far pascal FS_FILELOCKS (psffsi, psffsd, pUnLockRange, 

pLockRange, timeout, flags) 


struct sffsi far \ 
struct sffsd far \ 
struct filelock far \ 
struct filelock far \ 
unsigned long 
unsigned long 


psffsi; 

psffsd; 

pUnLockRange; 

pLockRange; 

timeout; 

flags; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pUnLockRange 

is a pointer to a filelock structure, identifying the range of the file to be unlocked. 
The filelock structure has the following format: 


struct filelock { 

unsigned long FileOffset; Aoffset where the lock/unlock begins X 
unsigned long RangeLength; //length of region locked/unlocked X 

} 


If RangeLength is zero, no unlocking is required. 

pLockRange 

is a pointer to a filelock structure, identifying the range of the file to be locked. If 
RangeLength is zero, no locking is required. 

timeout 

is the maximum time in milliseconds that the requestor wants to wait for the 
requested ranges, if they are not immediately available. 

flags 

specify what actions are to be taken depending on how the flag bits are set. 

flags 

is the bit mask which specifies what actions are to taken: 

SHARE Bit 0 on indicates other processes can share access to this locked 
range. Ranges with SHARE bit on can overlap. 

SHARE Bit 0 off indicates the current process has exclusive access to the 
locked range. An range with the SHARE bit off CANNOT overlap with any 
other lock range. 
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ATOMIC Bit 1 on indicates an atomic lock request. If the lock range equals 
the unlock range, an atomic lock will occur. If the ranges are not equal, an 
error will be returned. 

All other bits(2-31) are reserved and must be zero. 

Remarks 

This entry point was added to support the 32-bit DosSetFileLocks API. 

If the lock and unlock range lengths are both zero, an error, 
ERROR_LOCK_VIOLATION will be returned to the caller. If only a lock is desired, 
pUnLockRange can be NULL or both FileOffset and RangeLength should be set to 
zero when the call is made. The opposite is true for an unlock. 

When the atomic bit is not set, the unlock occurs first then the lock is performed. If 
an error occurs on the unlock, an error is returned and the lock is not performed. If 
an error occurs on the lock, an error is returned and the unlock remains in effect if 
one was requested. If the atomic bit is set and the unlock range equals the lock 
range and the unlock range has shared access but wants to change the access to 
exclusive access, the function is atomic. FSDs may not support atomic lock func- 
tions. If error ERROR_ATOMIC_LOCK_NOT_SUPPORTED is returned, the applica- 
tion should do an unlock and lock the range using non-atomic operations. The 
application should also be sure to refresh its internal buffers prior to making any 
modifications. 

Closing a file with locks still in force causes the locks to be released in no defined 
order. 

Terminating a process with a file open and having issued locks on that file causes 
the file to be closed and the locks to be released in no defined order. 

The figure below describes the level of access granted when the accessed region 
is locked. The locked regions can be anywhere in the logical file. Locking beyond 
end-of-file is not an error. It is expected that the time in which regions are locked 
will be short. Duplicating the handle duplicates access to the locked regions. 
Access to the locked regions is not duplicated across the DosExecPgm system call. 
The proper method for using locks is not to rely on being denied read or write 
access, but attempting to lock the region desired and examining the error code. 


Action 
Owner read 
Non-owner read 
Owner write 
Non-owner write 


Locked Access Table 
Exclusive Lock Shared Lock 

Success Success 

Return code, not block Success 
Success Return code, not block 

Return code, not block Return code, not block 


The locked access table has the actions on the left as to whether owners or non- 
owners of a file do either reads or writes of files that have exclusive or shared locks 
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set. A range to be locked for exclusive access must first be cleared of any locked 
subranges or locked any locked subranges or locked overlapping ranges. 
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FS_FINDCLOSE 

Directory Read (Search) Close 

Purpose 

Provides the mechanism for an FSD to release resources allocated on behalf of 
FS_FINDFIRST and FS_FINDNEXT. 

Calling Sequence 

int far pascal FS_FINDCLOSE (pfsfsi, pfsfsd) 

struct fsfsi far \ pfsfsi; 
struct fsfsd far \ pfsfsd; 


Where 

pfsfsi 

is a pointer to the file-system-independent file search structure. 

The FSD should not update this structure. 

pfsfsd 

is a pointer to the file-system-dependent file search structure. 

The FSD may use this to store information about continuation of its search. 

Remarks 

DosFindClose has been called on the handle associated with the search buffer. 
Any file system related information may be released. 

If FS_FINDFIFtST for a particular search returns an error, an FS_FINDCLOSE for 
that search will not be issued. 
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FS_FINDFIRST 

Find First Matching File Name(s) 

Purpose 

Find first occurrence(s) of matching file name(s) in a directory. 


Calling Sequence 


int far pascal FS_ 

JFINDFIRST (pcdfsi, pcdfsd, pName, iCurDirEnd, 

struct cdfsi far \ 

pcdfsi; 

attr, pfsfsi, pfsfsd, 
pData, cbData, pcMatch, lev 

struct cdfsd far \ 

pcdfsd; 


char far \ 

pName; 


unsigned short 

iCurDirEnd; 


unsigned short 

attr; 


struct fsfsi far \ 

pfsfsi; 


struct fsfsd far \ 

pfsfsd; 


char far \ 

pData; 


unsigned short 

cbData; 


unsigned short far \pcMatch; 


unsigned short 

level; 


unsigned short 

flags; 



Where 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pName 

is a pointer to the ASCIIZ name of the file or directory. 

Wildcard characters are allowed only in the last component. The FSD does not 
need to validate this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is provided to allow optimization of FSD path processing. If iCurDirEnd == 
-1 there is no current directory relevant to the name text, that is, a device. 

attr 

is a bit field that governs the match. 

Any directory entry whose attribute bit mask is a subset of attr and whose name 
matches that in pName should be returned. The attr field is two byte sized attri- 
bute bit masks. The least significant byte contains the "may have" bits. For 
example, a "may have" attribute of system and hidden is passed in. A file with 
the same name and an attribute of system is found. This file is returned. A file 
with the same name and no attributes (a regular file) is also returned. The "may 
have" attributes read-only and file-archive will not be passed in and should be 
ignored when comparing directory attributes. The most significant byte contains 
the "must have" bits. A file with a matching name must also have the attributes 
in the "must have" bits to be returned. See the OS/2 Version 3.0 Control 
Program Programming Reference for more information about the attribute field 
under DosFindFirst. 
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The value of attr passed to the FSD will be valid. The bit 0x0040 indicates a 
non-8.3 filename format. It should be treated the same way as system and 
hidden attributes are. You should not return a file name that does not conform 
to 8.3 filename format if this bit is not set in the "may have" bits. 

pfsfsi 

is a pointer to the file-system-independent file-search structure. 

The FSD should not update this structure. 

pfsfsd 

is a pointer to the file-system-dependent file-search structure. 

The FSD may use this to store information about continuation of the search. 

pData 

is the address of the application data area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). The FSD will fill in this area with a set of packed, variable- 
length structures that contain the requested data and matching file name. 

cbData 

is the length of the application data area in bytes. 

pcMatch 

is a pointer to the number of matching entries. 

The FSD returns, at most, this number of entries; the FSD returns in this 
parameter the number of entries actually placed in the data area. 

The FSD does not need to validate this pointer. 

level 

is the information level to be returned. 

Level selects among a series of data structures to be returned (see below). The 
level passed to the FSD is valid. 

flags 

indicates whether to return file-position information. 

flags == FF_NOPOS (0x00) indicates that file-position information should not be 
returned (see below). 

flags == FF_GETPOS (0x01) indicates that file-position information should be 

returned and the information format described below should be used. 

The flag passed to the FSD has a valid value. 

Remarks 

Note: 

The find structure passed back to the user is the structure defined for the 16 bit 
DosFindFirst API with some modification if the flags parameter is set. The basic, 
level one FILEFINDBUF structure is 
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struct FileFindBuf 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
long 
long 

unsigned short 
unsigned char 
unsigned char 

} 


{ 

dateCreate; 
timeCreate; 
dateAccess; 
timeAccess; 
date Write; 
timeWrite; 

cbEOF; 

cbAlloc; 

attr; 

cbName; 

szNamef]; 


For flags == 1 , the FSD must store in the first DWORD of the per-file attributes 
structure adequate information that in addition with the file name will allow the 
search to be resumed from the file by calling FS_FINDFROMNAME. For example, 
an ordinal representing the file's position in the directory could be stored. If the 
filename must be used to restart the search, the DWORD may be left blank. 


For level 0x0001 and flags == 1, directory information for FS_FINDFIRST is 
returned in the following format: 


struct FileFromFindBuf { 


long 

position; 

unsigned short 

dateCreate; 

unsigned short 

timeCreate; 

unsigned short 

dateAccess; 

unsigned short 

timeAccess; 

unsigned short 

date Write; 

unsigned short 

timeWrite; 

long 

cbEOF: 

long 

cbAlloc; 

unsigned short 

attr; 

unsigned char 

cbName; 

unsigned char 

szName[]; 


Aposition given to FSD on following X 
AFS_FINDFROMNAME call 


X 


The other information levels have similar format, with the position the first field in 
the structure for flags == 1 . For level 0x0002 and flags == 1 , directory information 
for FS_FINDFIRST is returned in the following format: 


struct FileFromFindBuf { 
long position; 


Athis field is not present if flags X 

/Ms 0 X 


unsigned short 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
long 
long 

unsigned short 
unsigned long 
unsigned char 
unsigned char 

} 


dateCreate; 
timeCreate; 
dateAccess; 
timeAccess; 
date Write; 
timeWrite; 

cbEOF; 

cbAlloc; 

attr; 

cbList; Asize of E As for the file X 

cbName; 
szNamef]; 
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For level 0x0003 and flags == 1, the directory information for FS_FINDFIRST is a 
bit more complicated. An EAOP struction will be located at the beginning of pData. 
You should start filling in the data after the EAOP structure. The data format is: 


struct FileFromFindBuf { 


long 

position; Athis field is not present if flags X 
Ais 0. 

unsigned short 

dateCreate; 

unsigned short 

timeCreate; 

unsigned short 

dateAccess; 

unsigned short 

timeAccess; 

unsigned short 

date Write; 

unsigned short 

timeWrite; 

long 

cbEOF; 

long 

cbAlloc; 

unsigned short 

attr; 

FEALIST 

fealist; Athis is a variable length field 

unsigned char 

cbName; 

unsigned char 

szNamef]; 


} 

For a description of the FEALIST structure, see “FEAs” on page 1-9. 

If the non-8.3 filename format bit is set in the attributes of a file found by 
FS_FINDFIFtST/NEXT/FFtOMNAME, it must be turned off in the copy of the attri- 
butes returned in pData. 

If FS_FINDFIRST for a particular search returns an error, an FS_FINDCLOSE for 
that search will not be issued. 

Sufficient information to find the next matching directory entry must be saved in the 
fsfsd data structure. 

In the case where directory entry information overflows the pData area, the FSD 
should be able to continue the search from the entry which caused the overflow on 
the next FS_FINDNEXT or FS_FINDFROMNAME. 

In the case of a global search in a directory, the first two entries in that directory as 
reported by the FSD should be and (current and the parent directories). 

Note: The FSD will be called with the FINDFIRST/FINDFROMNAME interface 
when the 32-bit DosFindFirst/DosFindNext APIs are called. THIS IS A CHANGE 
FROM 1.X IFS interface for redirector FSDs. The kernel will also be massaging the 
find records so that they appear the way the caller expects. Redirectors who have 
to resume searches should take this information into account, (i.e. You might want 
to reduce the size of the buffer sent to the server, so that the position fields can be 
added to the beginning of all the find records). 

Application Note: Some applications have been coded to expect behavior 
beyond the architectural requirements. For example, there are applications that 
require DosFindFirst to return an entry for a file that has been open-created, but 
which has never been closed. You can debate whether a file truly exists until it has 
been closed, but unless the applications are changed they will still not work. Con- 
sequently, it is recommended that FSDs exhibit this behavior. 
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FS_FINDFROMNAME 

Find matching file name(s) starting from name 


Purpose 

Find occurrence(s) of file name(s) in a directory starting from a position or name. 

Calling Sequence 

int far pascal FS_FINDFROMNAME (psfsfsi, pfsfsd, pData, cbData, pcMatch, 

level, position, pName, flags) 

struct fsfsi far \ pfsfsi; 

struct fsfsd far \ pfsfsd; 

char far \ pData; 

unsigned short cbData; 

unsigned short far \pcMatch; 
unsigned short level; 

unsigned long position; 

char far \ pName; 

unsigned short flags; 

Where 

pfsfsi 

is a pointer to the file-system-independent file search structure. The FSD 
should not update this structure. 

pfsfsd 

is a pointer to the file-system-dependent file search structure. The FSD may 
use this to store information about continuation of the search. 

pData 

is the address of the application data area. 

Addressing of this data area has not been validated by the kernel (see 
FSH_PROBEBUF). The FSD will fill in this area with a set of packed, variable- 
length structures that contain the requested data and matching file names in the 
format required for DosFindFirst/Next. 

cbData 

is the length of the application data area in bytes. 

pcMatch 

is a pointer to the number of matching entries. The FSD will return at most this 
number of entries. The FSD will store into it the number of entries actually 
placed in the data area. The FSD does not need to validate this pointer. 

level 

is the information level to be returned. Level selects among a series of struc- 
tures of data to be returned. The level passed to the FSD is valid. 

position 

is the file-system-specific information about where to restart the search from. 
This information was returned by the FSD in the FtesultBuf for a 
DosFindFirst2/Next/FromName call. 

pName 

is the filename from which to continue the search. The FSD does not need to 
validate this pointer. 
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flags 

indicates whether to return file position information. The flag passed to the FSD 
has a valid value. 

flags == FF_NOPOS (0x00) indicates that file-position information should not be 
returned, see FS_FINDFIRST. 

flags == FF_GETPOS (0x01) indicates that file-position information should be 
returned in the information format described under FS_FINDFIRST. 


Remarks 

The FSD may use the position or filename or both to determine the position from 
which to resume the directory search. Support of this entry point requires the 
ability to "resynch" or "rewind" a search request. The operating system can request 
that you start the search over with the file following the filename in pName. The 
information in position is the value that the FSD put in the position field in that 
file's FILEFINDBUF structure in a previous search request. 

For flags == 1 , the FSD must store in the position field adequate information to 
allow the search to be resumed from the file by calling FS_FINDFROMNAME. See 
FS_FINDFIRST for a description of the data format. 

The FSD must ensure that enough information is stored in the fsfsd data structure 
to enable it to continue the search. 

Note: The FSD will be called with the FINDFIRST/FINDFROMNAME interface 
when the 32-bit DosFindFirst/DosFindNext APIs are called. THIS IS A CHANGE 
FROM 1.X IFS interface for redirector FSDs. The kernel will also be massaging the 
find records so that they appear the way the caller expects. Redirectors who have 
to resume searches should take this information into account, (i.e. You might want 
to reduce the size of the buffer sent to the server, so that the position fields can be 
added to the beginning of all the find records). 
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FS_FINDNEXT 

Find next matching file name. 

Purpose 

Find the next occurrence of a file name in a directory. 

Calling Sequence 

int far pascal FSJINDNEXT (pfsfsi, pfsfsd, pData, cbData, pcMatch, 

level, flags) 


struct fsfsi far \ 
struct fsfsd far \ 
char far \ 
unsigned short 
unsigned short far \ 
unsigned short 
unsigned short 


pfsfsi; 

pfsfsd; 

pData; 

cbData; 

pcMatch; 

level; 

flags; 


Where 

pfsfsi 

is a pointer to the file-system-independent file-search structure. The FSD 
should not update this structure. 

pfsfsd 

is a pointer to the file-system-dependent file-search structure. The FSD may 
use this to store information about continuation of the search. 

pData 

is the address of the application area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). The FSD fills in this area with a set of packed, variable- 
length structures that contain the requested data and matching file names. 

cbData 

is the length of the application data area in bytes. 

pcMatch 

is a pointer to the number of matching entries. 

The FSD returns, at most, this number of entries. The FSD returns the the 
number of entries actually placed in the data area in this parameter. 

The FSD does not need to validate this pointer. 

level 

is the information level to be returned. Level selects among a series of struc- 
tures of data to be returned. The level passed to the FSD is valid. 

flags 

indicates whether to return file-position information. 

flags == FF_NOPOS (0x00) indicates that file-position information should not be 
returned, see FS_FINDFIRST. 

flags == FF_GETPOS (0x01) indicates that file-position information should be 
returned in the information format described under FS_FINDFIRST. 
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Remarks 

For flags == FF_GETPOS, the FSD must store in the position field adequate infor- 
mation to allow the search to be resumed from the file by calling 
FS_FINDFFtOMNAME. See FS_FINDFIRST for a description of the data format. 

The level passed to FS_FINDNEXT is the same level as that passed to 
FS_FINDFIRST to initiate the search. 

Sufficient information to find the next matching directory entry must be saved in the 
fsfsd data structure. 

The FSD should take care of the case where the pData area overflow may occur. 
FSDs should be able to start the search from the same entry for the next 
FS_FINDNEXT as the one for which the overflow occurred. 
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FS_FINDNOTIFYCLOSE 
Close Find-Notify Handle 

Purpose 

This function is now obsolete. The notification of file system changes is now being 
supported by the generic IFS mechanism. Removal of the entry point would result 
in unmodified FSDs being incompatible, so it was left in. Returning 
ERROR_NOT_SUPPORTED is recommended. The original function was to close 
the association between a Find-Notify handle and a DosFindNotifyFirst or 
DosFindNotifyNext function. 

Calling Sequence 

int far pascal FS_FINDNOTIFYCLOSE (handle) 
unsigned short handle; 


Where 

handle 

is the directory handle. 

This handle was returned by the FSD on a previous FS_FINDNOTIFYFIRST or 
FS_FINDNOTIFYNEXT call. 

Remarks 
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FS_FINDNOTIFYFIRST 
Monitor a directory for changes. 

Purpose 

This function is now obsolete. The notification of file system changes is now being 
supported by the generic IFS mechanism. Removal of the entry point would result 
in unmodified FSDs being incompatible, so it was left in. Returning 
ERROR_NOT_SUPPORTED is recommended. The original function was to start 
monitoring a directory for changes. 

Calling Sequence 

int far pascal FS_FINDNOTIFYFIRST ( pcdfsi, pcdfsd, pName, iCurDirEnd, 

attr, pFlandle, pData, cbData, pcMatch, 
level, timeout) 


struct cdfsi far \ 
struct cdfsd far \ 
char far \ 
unsigned short 
unsigned short 
unsigned short far \ 
char far \ 
unsigned short 
unsigned short far \ 
unsigned short 
unsigned long 


pcdfsi; 

pcdfsd; 

pName; 

iCurDirEnd; 

attr; 

pFiandle; 

pData; 

cbData; 

pMatch; 

level; 

timeout; 


Where 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pName 

is a pointer to the ASCIIZ name of the file or directory. 

Wildcard characters are allowed only in the last component. The FSD does not 
need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1 there is no 
current directory relevant to the name text, that is, a device. 

attr 

is the bit field that governs the match. 

Any directory entry whose attribute bit mask is a subset of attr and whose name 
matches that in pName should be returned. See FS_FINDFIRST for an expla- 
nation. 

pHandle 

is a pointer to the handle for the find-notify request. 

The FSD allocates a handle for the find-notify request, that is, a handle to the 
directory monitoring continuation information, and stores it here. This handle is 
passed to FS_FINDNOTIFYNEXT to continue directory monitoring. 
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The FSD does not need to verify this pointer. 

pData 

is the address of the application data area. 

Addressing of this data area is not validated by the kernel (see 
FSH&PROBEBUF). The FSD fills in this area with a set of packed, variable- 
length structures that contain the requested data and matching file names. 

cbData 

is the length of the application data area in bytes. 

pcMatch 

is a pointer to the number of matching entries. 

The FSD returns, at most, this number of entries. The FSD returns in this 
parameter the number of entries actually placed in the data area. 

The FSD does not need to verify this pointer. 

level 

is the information level to be returned. 

Level selects among a series of data structures to be returned. See the 
description of DosFindNotifyFirst in the OS/2 Version 3.0 Control Program Pro- 
gramming Reference for more information. 

The level passed to the FSD is valid. 

timeout 

is the timeout in milliseconds. 

The FSD waits until either the timeout has expired, the buffer is full, or the spec- 
ified number of entries has been returned before returning to the caller. 

Remarks 

None. 
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FS_FINDNOTIFYNEXT 

Resume reporting directory changes 

Purpose 

This function is now obsolete. The notification of file system changes is now being 
supported by the generic IFS mechanism. Removal of the entry point would result 
in unmodified FSDs being incompatible, so it was left in. Returning 
ERROR_NOT_SUPPORTED is recommended. The original function was to resume 
reporting of changes to a file or directory. 

Calling Sequence 

int far pascal FS_FINDNOTIFYNEXT ( handle, pData, cbData, pcMatch, 

level, timeout ) 


unsigned short 
char far \ 
unsigned short 
unsigned short far \ 
unsigned short 
unsigned long 


handle; 

pData; 

cbData; 

pcMatch; 

level; 

timeout; 


Where 

handle 

is the handle to the find-notify request. 

This handle was returned by the FSD and is associated with a previous 
FS_FINDNOTIFYFIRST or FS_FINDNOTIFYNEXT call. 

pData 

is the address of the application data area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). The FSD fills in this area with a set of packed, variable- 
length structures that contain the requested data and matching file names. 

cbData 

is the length of the application data area in bytes. 

pcMatch 

is a pointer to the number of matching entries. 

The FSD returns, at most, this number of entries. The FSD returns in this 
parameter the number of entries actually placed in the data area. 

The FSD does not need to verify this pointer. 

level 

is the information level to be returned. 

Level selects among a series of data structures to be returned. See the 
description of DosFindNotifyFirst in the OS/2 Version 3.0 Control Program Pro- 
gramming Reference for more information. 

The level passed to the FSD is valid. 

timeout 

is the timeout in milliseconds. 

The FSD waits until either the timeout has expired, the buffer is full, or the spec- 
ified number of entries has been returned before returning to the caller. 
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Remarks 

pcMatch is the number of changes required to directories or files that match the 
pName target and attr specified during a related, previous FS_FINDNOTIFYFIRST. 
The file system uses this field to return the number of changes that actually 
occurred since the issue of the present FS_FINDNOTIFYNEXT. 

The level passed to FS_FINDNOTIFYNEXT is the same level as that passed to 
FS_FINDNOTIFYFIRST to initiate the search. 
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FS_FLUSHBUF 
Commit file buffers 

Purpose 

Flushes cache buffers for a specific volume. 

Calling Sequence 

int far pascal FS_FLUSHBUF (hVPB, flag) 

unsigned short hVPB; 

unsigned short flag; 


Where 

hVPB 

is the handle to the volume for flush. 

flag 

is used to indicate discarding of cached data. 

flag == FLUSH_RETAIN (0x00) indicates cached data may be retained, 
flag == FLUSH_DISCARD (0x01) indicates the FSD will discard any cached 
data after flushing it to the specified volume. 

All other values are reserved. 

Remarks 

After this call is completed, the volume should be in a consistent state. In other 
words, if the media went off line, CFIKDSK should not find any discrepancy in your 
file system structure if the media was then mounted at a later date. "Dirty" flags 
may still be set, but the file system structures should be committed. 
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FS_FSCTL 

File System Control 


Purpose 

Allow an extended standard interface between an application and a file system 
driver. 

This is the official, architected way to implement any functions that are unique to 
your file system. The FSJOCTL is intended for functions that will be primarily ser- 
viced by the device driver. 

Calling Sequence 

int far pascal FS_FSCTL (pArgdat, iArgType, func, 

pPann, lenParm, plenParmlO, 
pData, lenData, plenDatalO) 


union argdat far \ 

pArgDat; 

unsigned short 

iArgType; 

unsigned short 

func; 

char far \ 

pParm; 

unsigned short 

lenParm; 

unsigned short far \ 

plenParmlO; 

char far \ 

pData; 

unsigned short 

lenData; 

unsigned short far \ 

plenDatalO; 

Where 


pArgDat 



is a pointer to the union whose contents depend on iArgType. The union is 
defined as follows: 

union argdat { 

ApArgType = 1, FileFlandle directed case X 
struct sf { 

struct sffsi far \psfsi; 
struct sffsd far \psfsd; 

}; 


ApArgType = 2, Pathname directed case X 
struct cd { 

struct cdfsi far \pcdfsi; 
struct cdfsd far Xpcdfsd; 
char far \ pPath; 

unsigned short iCurDirEnd; 

}; 


ApArgType = 3, FSD Name directed case X 
ApArgDat is Null X 

}; 

iArgType 

indicates the argument type. 

iArgType = FSCTL_ARG_FILEINSTANCE (0x01) 

means that pArgDat->sf.psfsi and pArgDat->sf.psfsd point to an sffsi and 
sffsd, respectively. 
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iArgType = FSCTL_ARG_CURDIR (0x02) 

means that pArgDat->cd.pcdfsi and pArgDat->cd.pcdfsd point to a cdfsi and 
cdfsd, pArgDat->cd.pPath points to a canonical pathname, and 
pArgDat->cd.iCurDirEnd gives the index of the end of the current directory 
in pPath. The FSD does not need to verify the pPath pointer. 
iArgType = FSCTL_ARG_NULL (0x03) 

means that the call was FSD name routed, and pArgDat is a NULL pointer. 

func 

indicates the function to perform. 

func == FSCTL_FUNC_NEW_INFO (0x01) indicates a request for new error 
code information. 

func == FSCTL_FUNC_EASIZE (0x02) indicates a request for the maximum 
EA size and EA list size supported by the FSD. 

pParm 

is the address of the application input parameter area. 

Addressing of this data area has not been validated by the kernel (see 
FSFLPROBEBUF). 

lenParm 

is the maximum length of the application parameter area (pParm). 

plenParmlO 

On input, contains the length in bytes of the parameters being passed in to the 
FSD in pParm. On return, contains the length in bytes of data returned in 
pParm by the FSD. The length of the data returned by the FSD in pParm must 
not exceed the length in lenParm. Addressing of this area is not validated by 
the kernel (see FSFLPROBEBUF). 

pData 

is the address of the application output data area. 

Addressing of this data area is not validated by the kernel (see 
FSFLPROBEBUF). 

lenData 

is the maximum length of the application output data area (pData). 

plenDatalO 

On input, contains the length in bytes of the data being passed in to the FSD in 
pData. On return, contains the length in bytes of data returned in pData by the 
FSD. The length of the data returned by the FSD in pData must not exceed the 
length in lenData. Addressing of this area is not validated by the kernel (see 
FSFLPROBEBUF). 

Remarks 

The accessibility of the parameter and data buffers has not been validated by the 
kernel. FS_PROBEBUF must be used. 

All FSDs must support func == 1 to return new error code information and func == 

2 to return the limits of the EA sizes. 

For func == 1 , the error code is passed to the FSD in the first WORD of the 
parameter area. On return, the first word of the data area contains the length of 
the asciiz string containing an explanation of the error code. The data area con- 


2-48 


DRAFT: OS/2 Installable File Systems 



tains the asciiz string beginning at the second WORD. Unfortunately, no current 
system code or utilities use this function. Consequently, it is recommended that 
FSDs try to restrict themselves to the standard return code set. In the future we 
may be able to use this as intended. 

For func == 2, the maximum EA and EA list sizes supported by the FSD are 
returned in the buffer pointed to by pData in the following format: 

EASizeBufStruc { 

unsigned short easb_MaxEASize; AMax size of an individual EA X 
unsigned long easb_MaxEAListSize; /\Max full EA list size X 

} 
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FS_FSINFO 

File System Information 


Purpose 

Returns or sets information for a file system device. 

Calling Sequence 

int far pascal FS_FSINFO (flag, hVPB, pData, cbData, level) 

unsigned short flag; 

unsigned short hVPB; 

char far \ pData; 

unsigned short cbData; 

unsigned short level; 


Where 

flag 

indicates retrieval or setting of information. 

flag == INFO_RETRIEVE (0x00) indicates retrieving information, 
flag == INFO_SET (0x01) indicates setting information on the media. 
All other values are reserved. 


hVPB 

is the handle to the volume of interest. 

pData 

is the address of the application output data area. 

Addressing of this data area has not been validated by the kernel (see 
(FSFLPROBEBUF). 

cbData 

is the length of the application data area. 

For flag == 0, this is the length of the data the application wishes to retrieve. If 
there is not enough room for the entire level of data to be returned, the FSD will 
return a BUFFER OVERFLOW error. For flag == 1, this is the length of the 
data to be sent to the file system. 

level 

is the information level to be returned. 

Level selects among a series of structures of data to be returned or set. See 
DosQFSInfo and DosSetFSInfo for information. 

Remarks 

None. 
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FSJNIT 

File system driver initialization 


Purpose 

Request file system driver initialization. 

Calling Sequence 

int far pascal FSJNIT ( szParm, DevFlelp, pMiniFSD ) 

char far \ szParm; 

unsigned long DevFlelp; 

unsigned long far \ pMiniFSD; 


Where 

szParm 

is a pointer to the ASCIIZ parameters following the CONFIG.SYS IFS= 
command that loaded the FSD. If there are no parameters, this pointer will be 
NULL. The FSD does not need to verify this pointer. 

Dev He Ip 

is the address of the kernel entry point for the DevHelp routines. 

This is used exactly as the device driver DevHelp address, and can be used by 
an FSD that needs access to some of the device helper services. 

pMiniFSD 

is a pointer to data passed between the mini-FSD and the FSD, or null. 

Remarks 

This call is made during system initialization to allow the FSD to perform actions 
necessary for beignning operation. The FSD may successfully initialize by 
returning a return code of NO_ERROR or may reject installation (invalid parame- 
ters, incompatible hardware, etc.) by returning the appropriate error code. If 
rejection is selected, all FSD selectors and segments are released. 

pMiniFSD will be null, except when booting from a volume managed by an FSD 
and the exported name of the FSD matches the exported name of the mini-FSD. 

In this case, pMiniFSD will point to data established by the mini-FSD (See 
m FSJNIT). 
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FSJOCTL 

I/O Control for Devices 


Purpose 

Perform control function on the device specified by the opened device handle. 

Calling Sequence 

int far pascal FSJOCTL (psffsi, psffsd, cat, func, 

pParm, lenMaxParm, plenlnOutParm, 
pData, lenMaxData, plenlnOutData) 


struct sffsi far \ 

psffsi; 

struct sffsd far \ 

psffsd; 

unsigned short 

cat; 

unsigned short 

func; 

char far \ 

pParm; 

unsigned short 

lenMaxParm: 

unsigned short \ 

plenlnOutParm; 

char far \ 

pData; 

unsigned short 

lenMaxData; 

unsigned short \ 

plenlnOutData; 

Where 


psffsi 



is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

cat 

is the category of the function to be performed. 

func 

is the function within the category to be performed. 

pParm 

is the address of the application input parameter area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). A null value indicates that the parameter is unspecified for 
this function. 

lenMaxParm 

is the byte length of the application input parameter area. 

If lenMaxParm is 0, *plenlnOutParm is 0, and pParm is not null, it means that 
the data buffer length is unknown due to the request being submitted via an old 
IOCTL or DosDevlOCtl interface. 

plenlnOutParm 

is the pointer to an unsigned short that contains the length of the parameter 
area in use on input and is set by the FSD to be the length of the parameter 
area in use on output. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). A null value indicates that the parameter is unspecified for 
this function. 
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pData 

is the address of the application output data area. 

Addressing of this data area has not been validated by the kernel (see 
FSH_PROBEBUF). A null value indicates that the parameter is unspecified for 
this function. 

lenMaxData 

is the byte length of the application output data area. 

If lenMaxData is 0, ‘plenlnOutData is 0, and pData is not null, it means that the 
data buffer length is unknown due to the request being submitted via an old 
IOCTL or DosDevlOCtl interface. 

plenlnOutData 

is the pointer to an unsigned short that contains the length of the data area in 
use on input and is set by the FSD to be the length of the data area in use on 
output. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). A null value indicates that the parameter is unspecified for 
this function. 

Remarks 

Note: This entry point's parameter list defintion has changed from the 1.x IFS doc- 
ument. If the parameters plenlnOutParm and plenlnOutData are null, use the 
lenMax parameters as the buffer sizes sent to any file system helper. 
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FS_MKDIR 
Make Subdirectory 


Purpose 

Create the specified directory. 

Calling Sequence 

int far pascal FS_MKDIR (pcdfsi, pcdfsd, pName, iCurDirEnd, pEABuf, flags) 

struct cdfsi far \ pcdfsi; 

struct cdfsd far \ pcdfsd; 

char far \ pName; 

unsigned short iCurDirEnd; 

char far \ pEABuf; 

unsighed short flags; 

Where 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pName 

is a pointer to the ASCIIZ name of the directory to be created. 

The FSD does not need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
current directory relevant to the name text, that is, a device. 

pEABuf 

is a pointer to the extended attribute buffer. 

This buffer contains attributes that will be set upon creation of the new directory. 
If NULL, no extended attributes are to be set. Addressing of this data area has 
not been validated by the kernel (see FSH_PROBEBUF). 

flags 

indicates the name type. 

Flags == 0x0040 indicates a non-8.3 filename format. All other values are 
reserved. 

Remarks 

The FSD needs to do the time stamping itself. There is no aid in the kernel for 
time stamping sub-directories. FAT only supports creation time stamp and sets the 
other two fields to zeroes. An FSD should do the same. The FSD can obtain the 
current time/date from the infoseg. 

A new directory called pName should be created if possible. The standard direc- 
tory entries and should be put into the directory. 

The non-8.3 filename format attribute in the directory entry should be set according 
to the value in flags. 
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FS_MOUNT 

Mount/unmount volumes 


Purpose 

Examination of a volume by an FSD to see if it recognizes the file system format. 


Calling Sequence 

int far pascal FS_MOUNT (flag, pvpfsi, pvpfsd, hVPB, pBoot) 


unsigned short 
struct vpfsi far \ 
struct vpfsd far \ 
unsigned short 
char far \ 


flag; 

pvpfsi; 

pvpfsd; 

hVPB; 

pBoot; 


Where 

flag 

indicates operation requested. 

flag == MOUNT_MOUNT (0x00) indicates that the FSD is requested to 
mount or accept a volume. 

flag == MOUNT_VOL_REMOVED (0x01) indicates that the FSD is being 
advised that the specified volume has been removed. 

flag == MOUNT_RELEASE (0x02) indicates that the FSD is requested to 
release all internal storage assigned to that volume as it has been removed 
from its driver and the last kernel-managed reference to that volume has 
been removed. 

flag == MOUNT_ACCEPT (0x03) indicates that the FSD is requested to 
accept the volume regardless of recognition in preparation for formatting for 
use with the FSD. 

All other values are reserved. 

The value passed to the FSD will be valid. 

pvpfsi 

is a pointer to the file-system-independent portion of VPB. 

If the media contains an OS/2-recognizable boot sector, then the vpi_vid field 
contains the 32-bit identifier for that volume. If the media does not contain such 
a boot sector, the FSD must generate a unique label for the media and place it 
into the vpi_vid field. 

pvpfsd 

is a pointer to the file-system-dependent portion of VPB. 

The FSD may store information as necessary into this area. 

hVPB 

is the handle to the volume 

pBoot 

is a pointer to sector 0 read from the media. 

This pointer is only valid when flag == 0. The buffer the pointer refers to must 
not be modified. The pointer is always valid and does not need to be verified 
when flag == 0. If a read error occurred, the buffer will contain zeroes. 
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Remarks 

The FSD examines the volume presented and determine whether it recognizes the 
file system. If it does, it returns zero, after having filled in appropriate parts of the 
vpfsi and vpfsd data structures. The vpi_vid and vpi_text fields must be filled in by 
the FSD. If the FSD has an OS/2 format boot sector, it must convert the label from 
the media into ASCIIZ form. The vpi_hDev field is filled in by OS/2. If the volume 
is unrecognized, the driver returns non-zero. 

The vpijext and vpi_vid must be updated by the FSD each time these values 
change. 

The contents of the vpfsd data structure are as follows: 

FLAG = 0 The FSD is expected to issue an FSD_FINDDUPFIVPB to see if a dupli- 
cate VPB exists. If one does exist, the VPB fs dependent area of the 
new VPB is invalid and the new VPB will be unmounted after the FSD 
returns from the MOUNT. The FSD is expected to update the FS 
dependent area of the old duplicate VPB. If no duplicate VPB exists, 
the FSD should initialize the FS dependent area. 

FLAG = 1 VPB FS dependent part is same as when FSD last modified it. 

FLAG = 2 VPB FS dependent part is same as when FSD last modified it. 

After media recognition time, the volume parameters may be examined using the 
FSH_GETVOLPARM call. The volume parameters should not be changed after 
media recognition time. 

During a mount request, the FSD may examine other sectors on the media by 
using FSH_DOVOLIO to perform the I/O. If an uncertain-media return is detected, 
the FSD is expected to clean up and return an UNCERTAIN MEDIA error in order 
to allow the volume mount logic to restart on the newly-inserted media. The FSD 
must provide the buffer to use for additional I/O. 

The OS/2 kernel manages the VPB through a reference count. All volume-specific 
objects are labelled with the appropriate volume handle and represent references to 
the VPB. When all kernel references to a volume disappear, FS_MOUNT is called 
with flag == 2, indicating a dismount request. 

When the kernel detects that a volume has been removed from its driver, but there 
are still outstanding references to the volume, FS_MOUNT is called with flag == 1 
to allow the FSD to drop clean (or other regenerable) data for the volume. Data 
which is dirty and cannot be regenerated should be kept so that it may be written to 
the volume when it is remounted in the drive. 

When a volume is to be formatted for use with an FSD, the kernel calls the FSD's 
FSJVIOUNT entry point with flag == 3 to allow the FSD to prepare for the format 
operation. The FSD should accept the volume even if it is not a volume of the type 
that FSD recognizes, since the point of format is to change the file system on the 
volume. The operation may fail if formatting does not make sense. (For example, 
an FSD which supports only CD-ROM.) 

Since the hardware does not allow for kernel-mediated removal of media, it is prob- 
able that the unmount request will be issued when the volume is not present in any 
drive. 
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FS_MOVE 

Move a file or subdirectory 


Purpose 

Moves (renames) the specified file or subdirectory. 


Calling Sequence 


int far pascal FS_ 

.MOVE (pcdfsi, pcdfsd. 


pSrc, iSrcCurDirEnd, 
pDst, iDstCurDirEnd, 
flags) 

struct cdfsi far \ 

pcdfsi; 

struct cdfsd far \ 

pcdfsd; 

char far \ 

pSrc; 

unsigned short 

iSrcCurDirEnd; 

char far \ 

pDst; 

unsigned short 

iDstCurDirEnd; 

unsigned short 

flags; 

Where 

pcsfsi 



is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pSrc 

is a pointer to the ASCIIZ name of the source file or directory. 

The FSD does not need to verify this pointer. 

iSrcCurDirEnd 

is the index of the end of the current directory in pSrc. 

This is used to optimize FSD path processing. If iSrcCurDirEnd == -1 there is 
no current directory relevant to the source name text. 

pDst 

is a pointer to the ASCIIZ name of the destination file or directory. 

The FSD does not need to verify this pointer. 

iDstCurDirEnd 

is the index of the end of the current directory in pDst. 

This is used to optimize FSD path processing. If iDstCurDirEnd == -1 there is 
no current directory relevant to the destination name text. 

flags 

indicates destination name type. 

Flags == 0x0040 indicates non-8.3 filename format. All other values are 
reserved. 
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Remarks 

The file specified in filename should be moved to or renamed as the destination 
filename, if possible. 

Neither the source nor the destination filename may contain wildcard characters. 
FSJVIOVE may be used to change the case in filenames. 

The non-8.3 filename format attribute in the directory entry for the destination name 
should be set according to the value in flags. 

In the case of a subdirectory move, the system does the following checking: 

No files in this directory or its subdirectories are open. 

This directory or any of its subdirectories is not the current directory for any 
process in the system. 

In addition, the system also checks for circularity in source and target directory 
names; that is, the source directory is not a prefix of the target directory. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFI_PFiOBEBUF where appropriate. 
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FS_NEWSIZE 

Change File's Logical Size 

Purpose 

Changes a file's logical (EOD) size. 

Calling Sequence 

int far pascal FS_NEWSIZE ( psffsi, psffsd, len, IOflag ) 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

unsigned long len; 

unsigned short IOflag; 

Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

len 

is the desired new length of the file. 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through. 

IOflag == IOFL_NOCACHE (0x0020) indicates no-cache. 

Remarks 

The FSD should return an error if an attempt is made to write beyond the end of 
the volume with a direct access device handle. 

The file system driver attempts to set the size (EOD) of the file to newsize and 
update sfi_size, if successful. If the new size is larger than the currently allocated 
size, the file system driver arranges for for efficient access to the newly-allocated 
storage. 

Of the information passed in IOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the 
device driver returns. The no-cache bit, on the other hand, is an advisory bit that 
says whether the data being transferred is worth caching or not. 

It is legal for the user to attempt to read an area of a file that has been allocated 
but not written to. Architecturally, that area is undefined and can be whatever data 
is in that area. Flowever, returning a zero-filled buffer for uninitialized file data is 
recommended. 
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FS_NMPIPE 

Do a remote named pipe operation. 


Purpose 

Perform a special purpose named pipe operation remotely. 

Calling Sequence 

int far pascal FSJSfMPIPE ( psffsi, psffsd, OpType, pOpRec, pData, pName ) 


struct sffsi far \ 
struct sffsd far \ 
unsigned short 
union npoper far \ 
char far \ 
char far \ 


psffsi; 

psffsd; 

OpType; 

pOpRec; 

pData; 

pName; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

OpType 

is the operation to be performed. This parameter has the following values: 


NMP_GetPHandState 

0x21 

NMP_SetPHandState 

0X01 

NMP__PipeQInfo 

0x22 

NMP__PeekPipe 

0x23 

NMP_ConnectPipe 

0x24 

NMP__DisconnectPipe 

0x25 

NMP_TransactPipe 

0x26 

NMP__ReadRaw 

0x11 

NMP_W riteRa w 

0x31 

NMP_W aitPipe 

0x53 

NMP_CallPipe 

0x54 

NMP_QNmPipeSemState 

0x58 


pOpRec 

is the data record which varies depending on the value of OpType. The first 
parameter in each structure encodes the length of the parameter block. The 
second parameter, if non-zero, indicates that the pData parameter is supplied 
and gives its length. The following record formats are used: 


union npoper { 


struct 

phs_param 

phs; 

struct 

npi_param 

npi; 

struct 

npr_param 

npr; 

struct 

npw_param 

npw; 

struct 

npq_param 

npq; 

struct 

npx_param 

npx; 

struct 

npp_param 

npp; 

struct 

npt_param 

npt; 

struct 

qnps_param 

qnps; 

struct 

npc_param 

npc; 

struct 

npd_param 

npd; 


}; 
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AGet/SetPhandState parameter block X 

struct phs_param { 

short phs_len; 

short phs_dlen; 

short phs_pmode; A pipe mode set or returned X 


ADosQNmPipelnfo parameter block X 

struct npLparam { 

short npLlen; 

short npi__dlen; 

short npi_level; A information level desired X 


/XDosRawReadNmPipe parameters X 
Adata is buffer addr X 

struct npr_param { 

short npr_len; 
short npr_dlen; 

short npr_nbyt; A number of bytes read X 


/XDosRawWriteNmPipe parameters X 
Adata is buffer addr X 

struct npw_param { 

short npw_len; 
short npw_dlen; 

short npw_nbyt; A number of bytes written X 


/XNPipeWait parameters X 
struct npq_param { 


short 

npq_len; 



short 

npq_dlen; 



long 

npq_timeo; 

Atimeout in milliseconds X 

short 

npq_prio; 

Apriority of caller 

X 


/XDosCallNmPipe parameters X 
Adata is in-buffer addr X 


struct npx_param { 
short 

unsigned short 
char far X 
unsigned short 
unsigned short 
long 


npx_len; 

npx_ilen; A length of in-buffer X 

npx_obuf; Apointer to out-buffer X 

npx_ilen; A length of out-buffer X 

npx_nbyt; A number of bytes read X 
npx_timeo; Atimeout in milliseconds X 


/XPeekPipe parameters, data is buffer addr X 
struct npp__param { 
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short npp_len; 

unsigned short npp_dlen; 

unsigned short npp_nbyt; A number of bytes read X 

unsigned short npp_avl0; A bytes left in pipe X 

unsigned short npp_avll; A bytes left in current msg X 
unsigned short npp_state; Apipe state X 


ADosTransactNmPipe parameters X 
Adata is in-buffer addr X 

struct npt jiaram { 

short npt_len; 

unsigned short npt_ilen; A length of in-buffer X 
char far \ npt_obuf; Apointer to out-buffer X 

unsigned short npt_olen; A length of out-buffer X 
unsigned short npt_nbyt; A number of bytes read X 

}; 


AQNmPipeSemState parameter block X 
Adata is user data buffer X 

struct qnps_param { 

unsigned short qnps_len; A length of parameter block X 
unsigned short qnps_dlen; A length of supplied data block X 
long qnps_semh; A system semaphore handle X 

unsigned short qnps_nbyt; A number of bytes returned X 


AConnectPipe parameter block, no data block X 
struct npc__param { 

unsigned short npc_len; Alength of parameter block X 
unsigned short npc_dlen; A length of data block X 


ADisconnectPipe parameter block, no data block X 
struct npd_param { 

unsigned short npd_len; Alength of parameter block X 
unsigned short npd_dlen; Alength of data block X 

}; 

pData 

is a pointer to a user data for operations which require it. When the pointer is 
supplied, its length will be given by the second element of the pOpRec struc- 
ture. 

pName 

is a pointer to a remote pipe name. Supplied only for NMP_WAITPIPE and 
NMP_CALLPIPE operations. For these two operations only, the psffsi and 
psffsd parameters have no significance. 
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Remarks 

This entry point is for support of special remote named pipe operations. Not all 
pointer parameters are used for all operations. In cases where a particular pointer 
has no significance, it will be NULL. 

This entry point will be called only for the UNC FSD. Non-UNC FSDs are required 
to have this entry point, but should return NOT SUPPORTED if called. 
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FS_OPENCREATE 
Open a file 


Purpose 

Opens (or creates) the specified file. 

Calling Sequence 

int far pascal FS_OPENCREATE (pcdfsi, pcdfsd, pName, iCurDirEnd, 

psffsi, psffsd, ulOpenMode, usOpenFlag, 
pusAction, usAttr, pcEABuf, pfgenflag) 


struct cdfsi far \ 

pcdfsi; 

struct cdfsd far \ 

pcdfsd; 

char far \ 

pName; 

unsigned short 

iCurDirEnd; 

struct sffsi far \ 

psffsi; 

struct sffsd far \ 

psffsd; 

unsigned long 

ulOpenMode; 

unsigned short 

usOpenFlag; 

unsigned short far \ 

pusAction; 

unsigned short 

usAttr; 

char far \ 

pcEABuf; 

unsigned short far \ 

pfgenflag; 

Where 


pcdfsi 



is a pointer to the file-system-independent working directory structure. 

The contents of this structure are invalid for direct access opens. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. The con- 
tents of this structure are invalid for direct access opens. For remote character 
devices, this field contains a pointer to a DWORD that was obtained from the 
remote FSD when the remote device was attached to this FSD. The FSD can 
use this DWORD to identify the remote device. 

pName 

is a pointer to the ASCIIZ name of the file to be opened. 

The FSD does not need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
current directory relevant to the name text, that is a device. This value is invalid 
for direct access opens. 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

ulOpenMode 

indicates the desired sharing mode and access mode for the file handle. 

See OS/2 Version 3.0 Control Program Programming Reference for a 
description of the OpenMode parameter for DosOpen. 
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An additional access mode 3 is defined when the file is being opened on behalf 
of OS/2, loaded for purposes of executing a file or loading a module. If the file 
system does not support an executable attribute, it should treat this access 
mode as open for reading. The value of ulOpenMode passed to the FSD will be 
valid. 

usOpenFlag 

indicates the action taken when the file is present or absent. 

See OS/2 Version 3.0 Control Program Programming Reference for a 
description of the usOpenFlag parameter for DosOpen. 

The value of openflag passed to the FSD is valid. This value is invalid for direct 
access opens. 

pus Act ion 

is the location where the FSD returns a description of the action taken as gov- 
erned by openflag. 

The FSD does not need to verify this pointer. The contents of Action are invalid 
on return for direct access opends. 

usAttr 

are the OS/2 file attributes. 

This value is invalid for direct access opens. 

pcEABuf 

is a pointer to the extended attribute buffer. 

This buffer contains attributes that will be set upon creation of a new file or upon 
replacement of an existing file. If NULL, no extended attributes are to be set. 
Addressing of this data area has not been validated by the OS/2 kernel (see 
FSH_PROBEBUF). The contents of EABuf are invalid on return for direct 
access opens. 

pfgenflag 

is a pointer to an unsigned short of flags returned by the FSD. The only flag 
currently defined is 0x0001 fGenNeedEA, which indicates that there are critical 
EAs associated with the file. The FSD does not need to verify this pointer. 

Remarks 

For the file create operation, if successful, ST_CREAT and ST_PCREAT are set. 
This causes the file to have zero as last read and last write time. If the last 
read/write time stamps are to be the same as the create time, simply set 
ST_SWRITE, ST_PWRITE, ST_SREAD, and ST_PREAD as well. 

For the file open operation, the FSD copies all supported time stamps from the 
directory entry into the SFT. 

Note: ALSO NEW FOR 2.0, it is suggested that the FSD copy the DOS file attri- 
butes from the directory entry into the SFT. This allows the FSD and the OS2 
kernel to handle FOB opens more efficently. 

The sharing mode may be zero if this is a request to open a file from the DOS 
mode or for an FOB request. 

FOB requests for read-write access to a read-only file are mapped to read-only 
access and reflected in the sfi_mode field by the FSD. An FOB request is indicated 
by the third bit set in the sfijype field. 
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The flags defined for the sfi_type field are: 

type == 0x0000 indicates file, 
type == 0x0001 indicates device, 
type == 0x0002 indicates named pipe, 
type == 0x0004 indicates FCB open. 

All other values are reserved. 

FSDs are required to initialize the sfijype field, preserving the FCB bit. 

On entry, the sfi_hvpb field is filled in. If the file's logical size (EOD) is specified, it 
is passed in the sfi_size field. To the extent possible, the file system tries to allo- 
cate this much storage for efficient access. 

Extended attributes are set for: 

1. the creation of a new file 

2. the truncation of an existing file 

3. the replacement of an existing file. 

They are not set for a normal open of an existing file. 

If the standard OS/2 file creation attributes are specified, they are passed in the attr 
field. To the extent possible, the file system interprets the extended attributes and 
applies them to the newly-created or existing file. Extended attributes (EAs) that 
the file system does not itself use are retained with the file and not discarded or 
rejected. 

When replacing an existing file, the FSD should not change the case of the existing 
file. 

FSDs are required to support direct access opens. These are indicated by a bit set 
in the sffsi.sfi_mode field. See OS/2 Version 3.0 Control Program Programming 
Reference for more information on DosOpen. Some of the parameters passed to 
the FSD for direct access opens are invalid, as described above. 

On a successful return, the following fields in the sffsi structure must be filled in by 
the file system driver: sfi_size and all the time and date fields. 

The file-system-dependent portion of an open file instance passed to the FSD for 
FS_OPENCREATE is never initialized. 

Infinite FCB opens of the same file by the same DOS mode process is supported. 
The first open is passed through to the FSD. Subsequent opens are not seen by 
the FSD. 

Any non-zero value returned by the FSD indicates that the open failed and the file 
is not open. 

Note: This entry point's parameter list defintion has changed from the 1 .x IFS doc- 
ument. The OpenMode parameter has been widened from a unsigned short to a 
unsigned long. The upper word of the long is relevant only to a special SPOOLER 
FSD. For information about the upper word please contact the OS/2 Techinal Inter- 
face group for the OEMI document for the 2.0 API 
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FS_OPENPAGEFILE 
Create paging file and handle 


Purpose 

Creates/opens the paging file for the Pager. 

Calling Sequence 

int far pascal FS_OPENPAGEFILE (pFlags, pcMaxReq, pName, psffsi, psffsd, 

usOpenMode, usOpenFlag, usAttr, Reserved) 


unsigned long far \ 

pFIag; 

unsigned long far \ 

pcMaxReq; 

char far \ 

pName; 

struct sffsi far \ 

psffsi; 

struct sffsd far \ 

psffsi; 

unsigned short 

usOpenMode; 

unsigned short 

usOpenFlag; 

unsigned short 

usAttr; 

unsigned long 

Reserved; 

Where 


pFIag 



is a pointer to a flag double word for passing of information between the pager 
and the file system. 

pFIag == PGIO_FIRSTOPEN (0x00000001) indicates first open of the page 
file. 

pFIag == PGIO_PADDR (0x00004000) indicates physical addresses are 
required in the page list. 

pFIag == PGIO_VADDR (0x00008000) indicates 16:16 virtual addresses are 
required in the page list. 

All other values are reserved. 

pcMaxReq 

is a pointer to a unsigned long where the FSD places the maximum request list 
length that can be managed by Enchanced strategy device driver. 

pName 

is a pointer to the ASCIIZ path and filename of the paging file. 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

usOpenMode 

indicates the desired sharing mode and access mode for the file handle. 

See OS/2 Version 3.0 Control Program Programming Reference for a 
description of the OpenMode parameter for DosOpen. 

usOpenFlag 

indicates the action taken when the file is present or absent. 

See OS/2 Version 3.0 Control Program Programming Reference for a 
description of the usOpenFlag parameter for DosOpen. 
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usAttr 

are the OS/2 file attributes. 

Reserved 

is a double word parameter reserved for use in the future. 

Remarks 

Enough information is provided for the FSD to perform a "normal" open/create call. 

Since a page file has special requirements about contiguity of its allocations, 
FS_OpenPageFile must assure that any data sectors allocated are returned (Create 
call only). FS_AllocatePageSpace will be called to handle file allocation. 

If the FSD cannot support the FS_DoPagelO (usually due to an disk device driver 
which does not support the Extended strategy entry point), the FSD can return zero 
(0) for *pcMaxFteq. This tells the kernel file system that it must emulate 
FS_DoPagelO. 

The FSD can require either physical or virtual (16:16) addresses for subsequent 
calls to FS_DoPagelO. This allows an FSD to emulate FS_DoPagelO without 
having to worry about dealing with physical addresses. 

For a detailed description of the Extended Strategy request interface please see the 
OS/2 Version 3.0 Physical Device Driver Reference. 
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FS_PATHINFO 

Query/Set a File's Information 


Purpose 

Returns information for a specific path or file. 

Calling Sequence 

int far pascal FS_PATHINFO (flag, pcdfsi, pcdfsd, pName, 

iCurDirEnd, level, pData, cbData) 


unsigned short 

flag; 

struct cdfsi far \ 

pcdfsi; 

struct cdfsd far \ 

pcdfsd; 

char far \ 

pName; 

unsigned short 

iCurDirEnd; 

unsigned short 

level; 

char far \ 

pData; 

unsigned short 

cbData; 

Where 


flag 



indicates retrieval or setting of information. 

flag == PI_RETRIEVE (0x0000) indicates retrieving information 
flag == PI_SET (0x0001) indicates setting information on the media 
flag == 0x0010 indicates that the information being set must be written- 
through onto the disk before returning. This bit is never set when retrieving 
information. 

All other values are reserved. 

pcdfsi 

is a pointer the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pName 

is a pointer to the ASCIIZ name of the file or directory for which information is to 
be retrieved or set. 

The FSD does not need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
current directory relevant to the name text, that is a device. 

level 

is the information level to be returned. 

Level selects among a series of data structures to be returned or set. 

pData 

is the address of the application data area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). When retrieval (flag == 0) is specified, the FSD places the 
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information into the buffer. When outputting information to a file (flag == 1), the 
FSD retrieves that data from the application buffer. 

cbData 

is the length of the application data area. 

For flag == 0, this is the length of the data the application wishes to retrieve. If 
there is not enough room for the entire level of data to be returned, the FSD 
returns a BUFFER OVERFLOW error. For flag == 1, this is the length of data 
to be applied to the file. 

Remarks 

See the descriptions of DosQPathlnfo and DosSetPathlnfo in the OS/2 Version 3.0 
Control Program Programming Reference for details on information levels. 

However, since the IFS architecture is still 16 Bit, the data structures that the FSD 
returns are the structures GEA, GEALIST, FEA, FEALIST, and EAOP- not the 
GEA2, GEA2LIST, etc. OS/2 will convert the structure to the appropriate 32 Bit 
form for 32 Bit applications. In addition to the information levels described in the 
OS/2 Version 3.0 Control Program Programming Reference level 4 support is 
required in all FSDs. For level 4, ignore the GEALIST and return all EAs to the 
caller in the FEALIST. The external publication of level 4 for 32 bit applications is 
being considered at this time. This call will not be officially supported for 16 Bit 
applications since we are hoping in the future to permit extended attributes to 
exceed 64K and that would break those applications. Also see the documentation 
of the FS_FILEINFO for a description of the 16 bit data structures. 

Note: This entry point should not modify the file size. 

The FSD will not be called for DosQPathlnfo level 5. 

FSDs that are case-preserving(like HPFS) can decide to accept level 7 requests. A 
level 7 DosQueryPathlnfo request asks the FSD to fill the pData buffer with the 
case-preserved path and filename of the path/filename passed in pName. Routing 
of level 7 requests will be determined by the kernel by checking the LV7 bit in a 
FSD's attribute double word. 
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FS_PROCESSNAME 

Allow FSD to modify name after OS/2 canonicalization 

Purpose 

Allow an FSD to modify filename to its own specification after the OS/2 
canonicalization process has completed. 

Calling Sequence 

int far pascal FS_PROCESSNAME (pNameBuf) 
char far \ pNameBuf; 


Where 

pNameBuf 

is a pointer to the ASCIIZ pathname. 

The FSD should modify the pathname in place. The buffer is guaranteed to be 
the length of the maximum path. The FSD does not need to verify this pointer. 

Remarks 

The resulting name must be within the maximum path length returned by 
DosQSysinfo. 

This routine allows the FSD to enforce a different naming convention than OS/2. 
For example, an FSD could remove blanks embedded in component names or 
return an error if it found such blanks. It is called after the OS/2 canonicalization 
process has succeeded. It is not called for FSFLCANONICALIZE. 

This routine is called for all APIs that use pathnames. 

This routine must return no error if the function is not supported. 

This routine is heavily utilized. The FSD should try to keep its performance 
optimal. 
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FS_READ 
Read from a File 

Purpose 

Read the specified number of bytes from a file to a buffer location. 

Calling Sequence 

int far pascal FS_READ ( psffsi, psffsd, pData, pLen, IOflag ) 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

char far \ pData; 

unsigned short far \ pLen; 

unsigned short IOflag; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

sfLposition is the location within the file where the data is to be read from. The 
FSD should update the sfLposition field. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pData 

is the address of the application data area. 

Addressing of this data area has not been validated by the kernel (see 
FShLPROBEBUF). 

pLen 

is a pointer to the length of the application data area. 

On input, this is the number of bytes to be read. On output, this is the number 
of bytes successfully read. If the application data area is smaller than the 
length, no transfer is to take place. The FSD will not be called for zero length 
reads. The FSD does not need to verify this pointer. 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through 
IOflag == IOFL_NOCACFIE (0x0020) indicates no-cache 

Remarks 

If read is successful and is a file, the FSD should set ST_SREAD and ST_PREAD 
to make the kernel time stamp the last modification time in the SFT. 

Of the information passed in IOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the 
device driver returns. The no-cache bit, on the other hand, is an advisory bit that 
says whether the data being transferred is worth caching or not. 

It is legal for the user to attempt to read an area of a file that has been allocated 
but not written to. Architecturally, that area is undefined and can be whatever data 
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is in that area. However, returning a zero-filled buffer for uninitialized file data is 
recommended. 

An attempt to read past the end of file should result in a zero return code and the 
contents of pLen set to the number of bytes successfully read until the end of file or 
zero if the entire read is beyond the end of the file. 

If an FSD supports file locking, it is responsible for checking if there are any locks 
on the file that should prevent the call from being executed. OS/2 will not do any 
lock checking if the FSA_LOCK bit is set in the FSD Attributes. 
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FS_RMDIR 

Remove Subdirectory 

Purpose 

Removes a subdirectory from the specified disk. 

Calling Sequence 

int far pascal FS_RMDIR (pcdfsi, pcdfsd, pName, iCurDirEnd) 

struct cdfsi far \ pcdfsi; 

struct cdfsd far \ pcdfsd; 

char far \ pName; 

unsigned short iCurDirEnd; 

Where 

pcdfsi 

is a pointer to the file-system-independent working directory structure. 

pcdfsd 

is a pointer to the file-system-dependent working directory structure. 

pName 

is a pointer to the ASCIIZ name of the directory to be removed. 

The FSD does not need to verify this pointer. 

iCurDirEnd 

is the index of the end of the current directory in pName. 

This is used to optimize FSD path processing. If iCurDirEnd == -1, there is no 
directory relevant to the name text, that is a device. 

Remarks 

OS/2 assures that the directory being removed is not the current directory nor the 
parent of any current directory of any process. 

The FSD should not remove any directory that has entries other than and in it. 
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FS_SETSWAP 

Notification of swap-file ownership 

Purpose 

Perform whatever actions are necessary to support the swapper. 

Calling Sequence 

int far pascal FS_SETSWAP (psffsi, psffsd) 

struct sffsi far \psffsi; 
struct sffsd far \psffsd; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance of the 
swapper file. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

Remarks 

Swapping does not begin until this call returns successfully. This call is made 
during system initialization. 

The FSD makes all segments that are relevant to swap-file I/O non-swappable (see 
FSH_FORCENOSWAP). This includes any data and code segments accessed 
during a read or write. 

Any FSD that manages writeable media may be the swapper file system. 

FS_SETSWAP may be called more than once for the same or different volumes or 
FSDs. 
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FS_SHUTDOWN 
Shutdown file system 

Purpose 

Used to shutdown an FSD in preparation for power-off or IPL. 

Calling Sequence 

int far pascal FS_SHUTDOWN (type, reserved) 
unsigned short type; 

unsigned long reserved; 


Where 

type 

indicates what type of a shutdown operation to perform. 

type == SD_BEGIN (0x00) indicates that the shutdown sequence is begin- 
ning. The kernel will not allow any new I/O calls to reach the FSD. The 
only exception will be I/O to the swap file by the swap thread through the 
FS_READ and FS_WRITE entry points. The kernel will still allow any thread 
to call FS_COMMIT, FS_FLUSHBUF and FS_SHUTDOWN. The FSD 
should complete all pending calls that might generate disk corruption. 

type == SD_COMPLETE (0x01) indicates that the shutdown sequence is 
ending. An FS_COMMIT has been called on every SFT open on the FSD 
and following that an FS_FLUSHBUF on all volumes has been called. All 
final clean up activity must be completed before this call returns. 

reserved 

reserved for future expansion. 

Remarks 

From the perspective of an FSD, the shutdown sequence looks like this: 

First, the system will call the FSD's FS_SHUTDOWN entry with type == 0. This 
notifies the FSD that the system will begin committing SFTs in preparation for 
system power off. The kernel will not allow any new 10 calls to the FSD once it 
receives this first call, except from the swapper thread. The swapper thread will 
continue to call the FS_READ and FS_WRITE entry points to read and write the 
swap file. The swapper thread will not attempt to grow or shrink the swap file nor 
should the FSD reallocate it. The kernel will continue to allow FS_COMMIT and 
FS_FLUSFIBUF calls from any thread. This call should not return from the FSD 
until disk data modifying calls have completed to insure that a thread already inside 
the FSD does not wake and change disk data. 

After the first FS_SFIUTDOWN call returns, the kernel will start committing SFTs. 
The FSD will see a commit for every SFT associated with it. During these 
FS_COMMIT calls, the FSD must flush any data associated with these SFTs to 
disk. The FSD must not allow any FS_COMMIT or FS_FLUSFIBUF call to block 
permanently. 

Once all of the SFTs associated with the FSD have been committed, 
FS_SHUTDOWN will be called with type == 1. This will tell the FSD to flush all 
buffers to disk. From this point, the FSD must not buffer any data destined for disk. 
Reads and writes to the swap file will continue, but the allocation of the swap file 
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will not change. Once this call has completed, no file system corruption should 
occur if power is shut off. 
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FS_VERIFYUNCNAME 
Verify UNC server ownership 

Purpose 

Used to poll installed UNC FSDs to determine server ownership. 

Calling Sequence 

int far pascal FS_VERIFYUNCNAME ( flag, pName ) 
unsigned short flag; 
char far \ pName; 

Where 

flag 

indicates which "pass" of the poll the FSD is being called. 

flag == VUN_PASS1 (0x0000) indicates that this is a pass 1 poll, 
flag == VUN_PASS2 (0x0001) indicates that this is a pass 2 poll. 

pName 

is a pointer to the ASCIIZ name of the server in UNC format. 

The FSD does not need to verify this pointer. 

Remarks 

What the kernel expects from UNC FSDs for this entry point: 

For pass 1, the FSD will be called and passed a pointer to the UNC server name. 

It is to respond immediately if it recongnizes(manages) the server with a 
NO_ERROR return code. This pass expects the that the FSD will be keeping 
tables in memory that contain the UNC names of the servers it is currently ser- 
vicing. If the UNC name cannot be validated immediately, the FSD should respond 
with an error (non-zero) return code. The FSD SFIOULD NOT send messages in 
an attempt to validate the server name. 

For pass 2, the FSD is permitted to do whatever is reasonable, including sending 
LAN "are you there" messages, to determine if they are able to service the request 
for UNC server. 
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FS_WRITE 
Write to a file 


Purpose 

Write the specified number of bytes to a file from a buffer location. 

Calling Sequence 

int far pascal FSJWRITE ( psffsi, psffsd, pDat, pLen, IOflag ) 

struct sffsi far \ psffsi; 

struct sffsd far \ psffsd; 

char far \ pData; 

unsigned short far \ pLen; 
unsigned short IOflag; 


Where 

psffsi 

is a pointer to the file-system-independent portion of an open file instance. 

sfLposition is the location within the file where the data is to be written to. The 
FSD should update the sfLposition and sfi_size fields. 

psffsd 

is a pointer to the file-system-dependent portion of an open file instance. 

pData 

is the address of the application data area. 

Addressing of this data area is not validated by the kernel (see 
FSH_PROBEBUF). 

pLen 

is a pointer to the length of the application data area. 

On input, this is the number of bytes that are to be written. On output, this is 
the number of bytes successfully written. If the application data area is smaller 
than the length, no transfer is to take place. The FSD does not need to verify 
this pointer. 

IOflag 

indicates information about the operation on the handle. 

IOflag == IOFL_WRITETHRU (0x0010) indicates write-through 
IOflag == IOFL_NOCACFIE (0x0020) indicates no-cache 

Remarks 

If write is successful and is a file, the FSD should set ST_SWRITE and 
ST_PWRITE to make the kernel time stamp the last modification time in the SFT. 

The FSD should return an error if an attempt is made to write beyond the end of 
the volume with a direct access device handle. 

Of the information passed in IOflag, the write-through bit is a mandatory bit in that 
any data written to the block device must be put out on the medium before the 
device driver returns. The no-cache bit, on the other hand, is an advisory bit that 
says whether the data being transferred is worth caching or not. 
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If an FSD supports file locking, it is responsible for checking if there are any locks 
on the file that should prevent the call from being executed. OS/2 will not do any 
lock checking if the FSA_LOCK bit is set in the FSD Attributes. 


Chapter 2. FS Service Routines 


2-81 



2-82 DRAFT: OS/2 Installable File Systems 



Chapter 3. FS Helper Functions 


The following table summarizes the routines that make up the File System Helper 
interface between FSDs and the kernel. 


FS Helper Routine 


Description 


FSH_ADDSHARE 

FSHJ3UFSTATE 

FSH_CALLDRIVER 

FSH_CANONICALIZE 

FSFLCHECKEANAME 

FSH_CRITERROR 

FSHJDEVIOCTL 

FSHJDOVOLIO 

FSFLD0V0LI02 

FSH_EXTENDTIMESLICE 

FSH_FINDCHAR 

FSH_FINDDUPHVPB 

FSFLFLUSFIBUF 

FSH_FORCENOSWAP 

FSHJ3ETBUF 

FSHJ3ETFIRSTOVERLAPBUF 
FSFIJ3ETPRIORITY 
FSH_GETVOLPARM 
FSHJNTERR 
FSHJOBOOST 
FSHJOSEMCLEAR 
FSHJSCURDIRPREFIX 
FSH_LOADCHAR 
FSH_NAMEFROMSFN 
FSH_PREVCHAR 
FSH_PROBEBUF 
FSH_QSYSINFO 
| FSFLQUERYOPLOCK 
| FSH_QUERYSERVERTHREAD 
FSH_REGISTERPERFCTRS 
FSFLRELEASEBUF 
FSH_REMOVESHARE 
FSH_SEGALLOC 
FSH_SEGFREE 
FSFLSEGREALLOC 
FSFLSEMCLEAR 
FSH_SEMREQUEST 
FSFLSEMSET 
FSFLSEMSETWAIT 
FSH_SEMWAIT 
FSH_SETVOLUME 
| FSHJ3TACKSPACE 
FSH_STORECHAR 
FSHJJPPERCASE 
FSHJ/VILDMATCH 
FSH_YIELD 


Add a name to the sharing set 

REMOVED in OS/2 Version 2.0 

Call Device Driver's Extended Strategy entry point 

Convert pathname to canonical form 

Check EA name validity 

Signal a hard error to the daemon 

Send IOCTL request to device driver 

Volume-based sector-oriented transfer 

Send volume-based IOCTL request to device driver. 

Request the kernel temporarily increase this thread's time slice 

Find first occurrence of char in string 

Locates equivalent hVPBs 

REMOVED in OS/2 Version 2.0 

Force segments permanently into memory 

REMOVED in OS/2 Version 2.0 

REMOVED in OS/2 Version 2.0 

Get current thread's I/O priority 

Get VPB data from VPB handle 

Signal an internal error 

Gives the current thread an I/O priority boost 

Clear an l/O-event semaphore 

Test for a prefix of a current directory 

Load character from a string 

Get the full path name from an SFN 

Move backward in string 

User address validity check 

Query system information 

Query if thread has oplock 

Query if thread is server thread 

Register a FSD with PERFVIEW 

REMOVED in OS/2 Version 2.0 

Remove a name from the sharing set 

Allocate a GDT or LDT segment 

Release a GDT or LDT segment 

Change segment size 

Clear a semaphore 

Request a semaphore 

Set a semaphore 

Set a semaphore and wait for clear 
Wait for clear 

force a volume to be mounted on the drive 

Query avilable stack space 

Store character into string 

Uppercase asciiz string 

Match using OS/2 wildcards 

Yield CPU to higher priority threads 


FSDs are loaded as dynamic link libraries and may import services provided by the 
kernel. These services can be called directly by the file system, passing the rele- 
vant parameters. 
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No validation of input parameters is done unless otherwise specified. The FSD 
calls FSH_PROBEBUF, where appropriate, before calling the FS help routine. 

When any service returns an error code, the FSD must return to the caller as soon 
as possible and return the specific error code from the helper to the FS router. 

There are many deadlocks that may occur as a result of operations issued by 
FSDs. OS/2 provides no means whereby deadlocks between file systems and 
applications can be detected. 
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FSH_ADDSHARE 

Add a name to the share set 

Purpose 

This function adds a name to the currently active sharing set. 

Calling Sequence 

int far pascal FSH_ADDSHARE (pName, mode, hVPB, phShare) 

char far \ pName; 

unsigned short mode; 

unsigned short hVPB; 

unsigned long far \ phShare; 


Where 

pName 

is a pointer to the ASCIIZ name to be added into the share set. 

The name must be in canonical form: no or components, uppercase, no 
meta characters, and full path name specified. 

mode 

is the sharing mode and access mode as defined in the DosOpen API. 

All other bits (direct open, write-through, etc.) must be zero. 

hVPB 

is the handle to the volume where the named object is presumed to exist. 

phShare 

is the pointer to the location where a share handle is stored. This handle may 
be passed to FSH_REMOVESHARE. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_SHARING_VIOLATION 

the file is open with a conflicting sharing/access mode. 

ERROR_TOO_MANY_OPEN_FILES 

there are too many files open at the present time. 

ERROR_SHARING_BUFFER_EXCEEDED 

there is not enough memory to hold sharing information. 

ERROR_INVALID„PARAMETER 

invalid bits in mode. 

ERROR_FILENAME_EXCED_RANGE 

path name is too long. 
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Remarks 

Do not call FSH_ADDSHARE for character devices. 

FSH.ADDSHARE may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFI_PROBEBUF where appropriate. 
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FSH_CALLDRIVER 

Call Device Driver's Extended Strategy entry point 

Purpose 

This routine allows FSDs to call a device driver's Extended Strategy entry point. 

Calling Sequence 

int far pascal FSH_C ALLDRIVER (pPkt , hVPB , fControl) 

void far \ pPkt; 

unsigned short hVPB; 

unsigned short fControl; 

Where 

pPkt 

is a pointer to device driver Extended strategy request packet. See OS/2 
Version 3.0 Physical Device Driver Reference for the packet format 

hVPB 

is the volume handle for the source of I/O. 

fControl 

is the bit mask of pop-up control actions: 

Bit 0 off indicates volume change pop-up desired 
Bit 0 on indicates no volume change pop-up 
All other bits are reserved and must be zero. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_VOLUME_CHANGED 

is an indication that removable media volume change has occured. 
ERROR_INVALID_PARAMETER 
the fControl flag word has reserved bits on. 

Remarks 

This routine should be called for any Extended strategy requests going to a drive 
that has removable media. 

For a detailed description of the Extended Strategy request interface please see the 
OS/2 Version 3.0 Physical Device Driver Reference. 

FSFLCALLDRIVER may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFI_PROBEBUF where appropriate. 

All data buffers that are to be accessed by the device driver should be locked by 
the FSD prior to using this call. The current way to accomplish this is to call the 
Device Driver Helpers VirtToLin followed by VMLock. See OS/2 Version 3.0 Phys- 
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ical Device Driver Reference for a description of these calls. This helper basically 
does a check to see if the volume has not been changed and then calls the device 
driver. The file system is responsible for the validity of the request packet. In addi- 
tion, if the file system wishes to correctly support the DosSetVerify API, the FSD 
should use FSH_QSYSINFO to determine the state of the verify bit and set the 
write command accordingly. 
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FSH_CANONICALIZE 

Convert a path name to a canonical form 

Purpose 

This function converts a path name to a canonical form by processing ’.’s and ’..’s, 
uppercasing, and prepending the current directory to non-absolute paths. 

Calling Sequence 

int far pascal FSH_CANONICALIZE (pPathName, cbPathBuf, 

pPathBuf, pFlags) 


char far \ pPathName; 

unsigned short cbPathBuf; 

char far \ pPathBuf; 

unsigned short far \ pFlags; 


Where 

pPathName 

is a pointer to the ASCIIZ path name to be canonicalized. 

cbPathBuf 

is the length of path name buffer. 

pPathBuf 

is the pointer to the buffer into which to copy the canonicalized path. 

pFlags 

is the pointer to flags returned to the FSD. 

Flags == 0x0040 indicates a non-8.3 filename format. All other values are 
reserved. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_PATH_NOT_FOUND 

is an invalid path name — too many ’..’s 

ERROR_BUFFEFt_OVERFLOW 

the path name is too long. 

Remarks 

This routine processes DBCS characters properly. 

The FSD is responsible for verifying the string pointers and checking for segment 
boundaries. 

FSFLCANONICALIZE should be called for names passed into the FSD raw data 
packets. For example, names passed to FS_FSCTL in the parameter area should 
be passed to FSFLCANONICALIZE. This routine does not need to be called for 
explicit names passed to the FSD, that is, the name passed to FS_OPENCREATE. 

If the canonicalized name is being created as a file or directory, the non-8.3 attri- 
bute in the directory entry should be set according to the value returned in pFlags. 
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Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSH_PROBEBUF where appropriate. 
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FSH_CHECKEANAME 
Check for valid EA name 

Purpose 

Check extended attribute name validity. 

Calling Sequence 

int far pascal FSH_CHECKEANAME (iLevel, cbEAName, szEAName) 

unsigned short iLevel; 
unsigned long cbEAName; 
char far \ szEAName; 

Where 

iLevel 

is the extended attributes name checking level. 

iLevel = 0x0001 indicates OS/2 Version 3.0 name checking. 

cbEAName 

is the length of the extended attribute name, not including terminating NUL. 
szEAName 

is the extended attribute name to check for validity. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_NAME 

pathname contains invalid or wildcard characters, or is too long. 
ERROR_INVALID__PARAMETER 
invalid level. 

Remarks 

This routine processes DBCS characters properly. 

The set of invalid characters for EA names is the same as that for filenames. In 
OS/2 Version 3.0, the maximum length of an EA name, not including the termi- 
nating NUL, is 255 bytes. The minimum length is 1 byte. 

The FSD is responsible for verifying the string pointers and checking for segment 
boundaries. 

FSH_CHECKEANAME should be called for extended attribute names passed to the 
FSD. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSH_PROBEBUF where appropriate. 
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FSH_CRITERROR 

Signal hard error to daemon 

Purpose 

This function signals a hard error to the daemon. 

Calling Sequence 

int far pascal FSH_CRITERROR (cbMessage, pMessage, nSubs, 

pSubs, fAllowed) 

unsigned short cbMessage; 
char far \ pMessage; 

unsigned short nSubs; 

char far \ pSubs; 

unsigned short fAllowed; 

Where 

cbMessage 

is the length of the message template. 

pMessage 

is the pointer to the message template. 

This may contain replaceable parameters in the format used by the message 
retriever. 

nSubs 

is the number of replaceable parameters. 

pSubs 

is the pointer to the replacement text. 

The replacement text is a packed set of ASCIIZ strings. 

fAllowed 

is the bit mask of allowed actions: 

CE_ALLFAIL, Bit 0x0001 on indicates FAIL allowed 

CE_ALLABORT, Bit 0x0002 on indicates ABORT allowed 

CE_ALLRETRY, Bit 0x0004 on indicates RETRY allowed 

CE_ALLIGNORE, Bit 0x0008 on indicates IGNORE allowed 

CE_ALLACK, Bit 0x0010 on indicates ACKNOWLEDGE only allowed. 

All other bits are reserved and must be zero. If bit 0x0010 is set, and any or 
some of bits 0x0001 to 0x0008 are also set, bit 0x0010 will be ignored. 

Returns 

This function returns the action to be taken: 

CE_RETIGNORE, 0x0000 - ignore 
CE_RETRETRY, 0x0001 - retry 
CE_RETFAIL, 0x0003 - fail 
CE_RETACK, 0x0004 - continue 
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Remarks 

If the user responds with an action that is not allowed, it is treated as FAIL. If FAIL 
is not allowed, it is treated as ABORT. ABORT is always allowed. 

When ABORT is the final action, OS/2 does not return this as an indicator; it 
returns a FAIL. The actual ABORT operation is generated when this thread of exe- 
cution is about to return to user code. 

The maximum length of the template is 128 bytes, including the NUL. The 
maximum length of the message with text substitutions is 512 bytes. The 
maximum number of substitutions is 9. 

If any action other than retry is selected for a given hard error popup, then any 
subsequent popups (within the same API call) will be automatically failed; a popup 
will not be done. This means that (except for retries) there can be at most one 
hard error popup per call to the FSD. And, if the kernel generates a popup, then 
the FSD cannot create one. 

FSH_CRITERROR will fail automatically if the user application has set autofail, or if 
a previous hard error has occurred. 

FSH_CRITERROR may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSH_PROBEBUF where appropriate. 
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FSH_DEVIOCTL 

Send IOCTL request to device driver 

Purpose 

This function sends an IOCTL request to a device driver. 

Calling Sequence 

int far pascal FSH_DEVIOCTL ( flag, hDev, sfn, cat, func, pParm, cbParm, 

pData, cbData ) 


unsigned short 

flag; 

unsigned long 

hDev; 

unsigned short 

sfn; 

unsigned short 

cat; 

unsigned short 

func; 

char far \ 

pParm; 

unsigned short 

cbParm; 

char far \ 

pData; 

unsigned short 

cbData; 

Where 


flag 



indicates whether the FSD initiated the call or not. 

lOflag == 0x0000 indicates that the FSD is just passing user pointers on to 
the helper. 

lOflag == 0x0001 indicates that the FSD initiated the DevlOCtl call as 
opposed to passing a DevlOCtl that it had received. 

All other bits are reserved. 


hDev 

is the device handle obtained from VPB 


sfn 

is the system file number from open instance that caused the FSH_DEVIOCTL 
call. 

This field should be passed unchanged from the sfi_selfsfn field. If no open 
instance corresponds to this call, this field should be set to OxFFFF. 

cat 

is the category of IOCTL to perform. 

func 

is the function within the category of IOCTL. 

pParm 

is the long address to the parameter area. 

cbParm 

is the length of the parameter area. 

pData 

is the long address to the data area. 

cbData 

is the length of the data area. 
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Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_FUNCTION 

indicates the function supplied is incompatible with the category and device 
handle supplied. 

ERRORJNVALIDCATEGORY 

indicates the category supplied is incompatible with the function and device 
handle supplied. 

Device driver error code 

Remarks 

The only category currently supported for this call is 8, which is for the logical disk. 
FSDs call FSELDEVIOCTL to control device driver operation independently from 
I/O operations. This is typically in filtering DosDevlOCtl requests when passing the 
request on to the device driver. 

An FSD needs to be careful of pointers to buffers that are passed to it from 
FSJOCTL, and what it passes to FSH_DEVIOCTL. It is possible that such pointers 
may be real mode pointers if the call was made from the DOS mode. In any case, 
the FSD must indicate whether it initiated the DevlOCtl call, in which case the 
kernel can assume that the pointers are all protect mode pointers, or if it is passing 
user pointers on to the FSFI_DEVIOCTL call, in which case the mode of the 
pointers will depend on whether this is the DOS mode or not. An important thing to 
note is that the FSD must not mix user pointers with its own pointers when using 
this helper. 

FSELDEVIOCTL may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSH_PROBEBUF where appropriate. 
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FSH_DOVOLIO 

Transfer volume-based sector-oriented I/O 

Purpose 

This function performs I/O to the specified volume. 

Calling Sequence 

int far pascal FSH„DOVOLIO (operation, fAllowed, hVPB, 

pData, pcSec, iSec) 


unsigned short 
unsigned short 
unsigned short 
char far \ 

unsigned short far \ 
unsigned long 


operation; 

fAllowed; 

hVPB; 

pData; 

pcSec; 

iSec; 


Where 

operation 

is the bit mask indicating read/read-bypass/write/write-bypass, and verify-after- 
write/write-through and no-cache operation to be performed. 

DVIO_OPREAD, Bit 0x0001 off indicates read. 

DVIO_OPWRITE, Bit 0x0001 on indicates write. 

Bit 0x0002 off indicates no cache bypass. 

DVIO_OPBYPASS, Bit 0x0002 on indicates cache bypass. 

Bit 0x0004 off indicates no verify-after-write operation. 

DVIO_OPVERIFY, Bit 0x0004 on indicates verify-after-write operation. 

Bit 0x0008 off indicates errors signalled to the hard error daemon. 
DVIO_OPHARDERR, Bit 0x0008 on indicates hard errors will be returned 
directly. 

Bit 0x0010 off indicates I/O is not write-through. 

DVIO_OPWRTHRU, Bit 0x0010 on indicates I/O is write-through. 

Bit 0x0020 off indicates data for this I/O should probably be cached. 
DVIO_OPNCACHE, Bit 0x0020 on indicates data for this I/O should prob- 
ably not be cached. 

Bit 0x0040 off indicate that memory should be locked. 

DVIO_OPRESMEM, Bit 0x0040 on indicates the memory should not be 
locked. 

All other bits are reserved and must be zero. 

The difference between the cache bypass and the no cache bits is in the type of 
request packet that the device driver will see. With cache bypass, it will get a 
packet with command code 24, 25, or 26. With no cache, it will get the 
extended packets for command codes 4, 8, or 9. The advantage of the latter is 
that the write-through bit can also be sent to the device driver in the same 
packet, improving the functionality at the level of the device driver. 

fAllowed 

is a bit mask indicating allowed actions: 

DVIO_ALLFAIL, Bit 0x0001 on indicates FAIL allowed 
DVIO_ALLABORT, Bit 0x0002 on indicates ABORT allowed 
DVIO_ALLRETRY, Bit 0x0004 on indicates RETRY allowed 
DVIO_ALLIGNORE, Bit 0x0008 on indicates IGNORE allowed 
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DVIO_ALLACK, Bit 0x0010 on indicates ACKNOWLEDGE only allowed 
If this bit is set, none of the other bits may be set. 

All other bits are reserved and must be set to zero. 

hVPB 

is the volume handle for the source of I/O. 

pData 

is the long address of the user transfer area. 

pcSec 

is the pointer to the number of sectors to be transferred. 

On return, this is the number of sectors successfully transferred. 

iSec 

is the sector number of the first sector of the transfer. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_PROTECTION_VIOLATION 

indicates the supplied address/length is invalid. 

ERROR_UNCERTAIN_MEDIA 

indicates the device driver can no longer reliably tell if the media has been 
changed. 

This occurs only within the context of an FS_MOUNT call. 
ERROR_TRANSFER_TOO_LONG 
indicates the transfer is too long for the device. 

Device-driver/device-manager errors listed /DDERR/ 

Remarks 

This function formats a device driver request packet for the requested I/O, locks the 
data transfer region, calls the device driver, and reports any errors to the hard error 
daemon before returning to the FSD. Any retries indicated by the hard error 
daemon or actions indicated by DosError are done within the call to 
FSH_DOVOLIO. 

FSH_DOVOLIO may be used at all times within the FSD. When called within the 
scope of a FS_MOUNT call, it applies to the volume in the drive without regard to 
which volume it may be. However, since volume recognition is not complete until 
the FSD returns to the FS_MOUNT call, the FSD must be careful when an 
ERROR_UNCERTAINJVIEDIA is returned. This indicates the media has gone 
uncertain while we are trying to identify the media in the drive. This may indicate 
the volume that the FSD was trying to recognize was removed. In that case, the 
FSD must release any resources attached to the hVPB passed in the FS_MOUNT 
call and return ERROR_UNCERTAIN_MEDIA to the FS_MOUNT call. This will 
direct the volume tracking logic to restart the mount process. 

OS/2 will validate the user transfer area for proper access and size and will lock the 
segment. 
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Verify-after-write specified on a read is ignored. 


On 80386 processors, FSH_DOVOLIO will take care of memory contiguity require- 
ments of device drivers. It is advisable, therefore, that FSDs use FSFLDOVOLIO 
instead of calling device drivers directly. This will improve performance of FSDs 
running on 80386 processors. 

FSH_DOVOLIO may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_D0V0LI02 

Send volume-based IOCTL request to device driver 

Purpose 

This function is an FSD call that controls device driver operation independently from 
I/O operations. 

Calling Sequence 

int far pascal FSH_D0V0LI02 (hDev, sfn, cat, func, pParm, cbParm, 

pData, cbData) 

unsigned long hDev; 

unsigned short sfn; 

unsigned short cat; 

unsigned short func; 

char far \ pParm; 

unsigned short cbParm; 
char far \ pData; 

unsigned short cbData; 

Where 

hDev 

is the device handle obtained from VPB 

sfn 

is the system file number from the open instance that caused the 
FSD_DEVIOCTL call. 

This field should be passed unchanged from the sfi-selfsfn field. It no open 
instance corresponds to this call, this field should be set to OxFFFF. 

cat 

is the category of IOCTL to perform. 

func 

is the function within the category of IOCTL. 

pParm 

is the long address to the parameter area. 

cbParm 

is the length of the parameter area. 

pData 

is the long address to the data area. 

cbData 

is the length of the data area. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID__FUNCTION 

indicates the function supplied is incompatible with the category and the device 
handle supplied. 

ERROR_INVALID„CATEGORY 
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indicates the category supplied is incompatible with the function and the device 
handle supplied. 

Device-driver/device-manager errors listed /DDERR/ 

Remarks 

This routine supports volume management for IOCTL operations. Any errors are 
reported to the hard error daemon before returning to the FSD. Any retries indi- 
cated by the hard error daemon or actions indicated by DosError are done within 
the call to FSH_D0V0LI02. 

The purpose of this routine is to enable volume tracking with lOCTLs. It is not 
available at the API level. 

FSFLD0V0LI02 may block. 

System does normal volume checking for this request. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_EXTENDTIMESLICE 

Notify kernel that temporarily increasing this thread's time slice is 
advisable. 


Purpose 

Notify kernel to temporarily increasing this thread's time slice. 

This helper is new to OS/2 3.0. It is currently being used internally if a cache hit 
occurred to temporarily increase the current thread's time slice because the proba- 
bility is high that additional I/O requests will also be in the cache. This resulted in a 
performance gain. 

This call needs to be used carefully. Improper use can result in performance 
degradation in different environments. In addition, OS/2 development believes that 
there is a good probability that the function or calling parameters for this helper 
may need modification for optimal performance in future releases. Consequently, 
use this helper with appropriate care- it may result in otherwise unnecessary level 
sensitivity to future releases. 

Calling Sequence 

int far pascal FSH_EXTENDTIMESLICE () 

Where 

There are no parameters to this helper. 

Returns 

The return code may be ignored. 
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FSH_FINDCHAR 

Find first occurrence of character in string 

Purpose 

This function provides the mechanism to find the first occurrence of any one of a 
set of characters in an ASCIIZ string, taking into account DBCS considerations. 

Calling Sequence 

int far pascal FSHJINDCHAR (nChars, pChars, ppStr) 

unsigned short nChars; 

char far \ pChars; 

char far Tar \ ppStr; 


Where 

nChars 

is the number of characters in the search list. 
pChars 

is the array of characters to search for. These cannot be DBCS characters. 

The NUL character cannot be searched for. 

ppSTR 

is the pointer to the character pointer where the search is to begin. This pointer 
is updated upon return to point to the character found. This must be an ASCIIZ 
string. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_CHAR_NOT_FOUND 

indicates none of the characters were found. 

Remarks 

The search will continue until a matching character is found or the end of the string 
is found. 

The FSD is responsible for verifying the string pointers and checking for segment 
boundaries. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_FINDDUPHVPB 
Locate equivalent hVPB 

Purpose 

This function provides the mechanism to identify a previous instance of a volume 
during the FS_MOUNT process. 

Calling Sequence 

int far pascal FSHFINDDUPHVPB (hVPB, phVPB) 

unsigned short hVPB; 

unsigned short far \ phVPB; 


Where 

hVPB 

is the handle to the volume to be found. 

phVPB 

is the pointer to where the handle of matching volume will be stored. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROFLNOJTEMS 

indicates there is no matching hVPB. 

Remarks 

When OS/2 is recognizing a volume, it calls the FSD to mount the volume. At this 
point, the FSD may elect to allocate storage and buffer data for that volume. The 
mount process will allocate a new VPB whenever the media becomes uncertain, 
that is, when the device driver recognizes it can no longer be certain the media is 
unchanged. This VPB cannot be collapsed with a previously allocated VPB, 
because of a reinsertion of media, until the FS_MOUNT call returns. The previous 
VPB, however, may have some cached data that must be updated from the media 
(the media may have been written while it was removed) FSDJRNDDUPHVPB 
allows the FSD to find this previous occurrence of the volume in order to update 
the cached information for the old VPB. Remember the newly created VPB will be 
unmounted if there is another, older VPB for that volume. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_FORCENOSWAP 

Force segments permanently into memory 

Purpose 

This function permanently forces segments into memory. 

Calling Sequence 

int far pascal FSHFORCENOSWAP (sel) 
unsigned short sel; 


Where 

sel 

is the selector that is to be made non-swappable. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_ACCESS 

indicates the selector is invalid. 

ERROR_INVALID_DENIED 

indicates the selector is invalid or the sector belongs to another process. 
ERROR_DIRECT_ACCESS_HANDLE 
indicates the handle does not refer to a segment. 
ERROR_NOT_ENOUGH_MEMORY 

indicates there is not enough physical memory to make a segment non- 
swappable. 

ERROR_SWAP_TABLE_FULL 
indicates the attempt to grow the swap file failed. 

ERROR_SWAP_FILE_FULL 
indicates the attempt to grow the swap file failed. 
ERROR_PMM_INSUFFICIENT_MEMORY 
indicates the attempt to grow the swap file failed. 

Remarks 

An FSD may call FSH_FORCENOSWAP to force segments to be loaded into 
memory and marked non-swappable. All segments both in the load image of the 
FSD and those allocated via FSFLSEGALLOC are eligible to be marked. There is 
no way to undo the effect of FSH_FORCENOSWAP. 

If an FSD is notified it is managing the swapping media, it should make this call for 
the necessary segments. 

An FSD should be prepared to see multiple swapping files on more than one 
volume in 80386 processors and in future releases of OS/2. 
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FShLFORCENOSWAP may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PFiOBEBUF where appropriate. 
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FSH_GETPRIORITY 

Get current thread's I/O priority 

Purpose 

This function allows an FSD to retrieve the I/O priority of the current thread. 

Calling Sequence 

int far pascal FSH_GETPRIORITY (void) 


Returns 

This function returns the I/O priority of the current thread: 
0x0000 - background 
0x1 1 1 1 - foreground 

Remarks 

FSH_GETPRIORITY will not block. 
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FSH_GETVOLPARM 

Get VPB data from VPB handle 

Purpose 

This function allows an FSD to retrieve file-system-independent and file-system- 
dependent data from a VPB. Since the FS router passes in a VPB handle, indi- 
vidual FSDs need to map the handle into pointers to the relevant portions. 

Calling Sequence 

void far pascal FSH_GETVOLPARM (hVPB, ppVPBfsi, ppVPBfsd) 

unsigned short hVPB; 

struc vpfsi far Yfar \ ppVPBfsi; 
struc vpfsd far \far \ ppVPBfsd; 


Where 

hVPB 

is the volume handle of interest. 

ppVPBfsi 

indicates the location where the pointer to file-system-independent data is 
stored. 

ppVPBfsd 

indicates the location where the pointer to file-system-dependent data is stored. 

Returns 

There are no error returns. 

Remarks 

FSFLGETVOLPARM will not block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFLPFiOBEBUF where appropriate. 
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FSHJNTERR 
Signal an internal error 

Purpose 

This function signals an internal error. 

Calling Sequence 

void far pascal FSHJNTERR (pMsg, cbMsg) 

char far \ pMsg; 

unsigned short cbMsg; 


Where 

pMsg 

is a pointer to the message text. 

cbMsg 

is the length of the message text. 

Returns 

There are no error returns. 

Remarks 

For reliability, if an FSD detects an internal inconsistency during normal operation, 
the FSD shuts down the system as a whole. This is the safest thing to do since it 
is not clear if the system as a whole is in a state that allows normal execution to 
continue. 

When an FSD calls FSHJNTERR, the address of the caller and the supplied 
message is displayed on the console. The system then halts. 

The code used to display the message is primitive. The message should contain 
ASCII characters in the range 0x20-0x7E, optionally with OxOD and OxOA to break 
the text into multiple lines. 

The FSD must preface all such messages with the name of the file system. 

The maximum message length is 512 characters. Messages longer than this are 
truncated. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSHJOBOOST 

Gives the current thread an I/O priority boost 

Purpose 

This function allows an FSD to boost the current thread's I/O priority after a I/O 
request. 

Calling Sequence 

void far pascal FSHJOBOOST (void) 


Returns 

There are no error returns. 

Remarks 

FSHJOBOOST will not block. 
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FSHJOSEMCLEAR 

Clear an I/O event semaphore 

Purpose 

This function allows an FSD to clear the I/O event semaphore that is a part of the 
Extended Strategy request packet. 

Calling Sequence 

int far pascal FSHJOSEMCLEAR (pSem) 


Where 

pSem 

is the handle to the I/O event semaphore. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_EXCL_ALREADY_OWNED 

the exclusive semaphore is already owned. 

ERROR_PROTECTION_VIOLATION 

the semaphore is inaccessible. 

Remarks 

FSHJOSEMCLEAR may block. 

For a detailed description of the Extended Strategy request interface please see 
the OS/2 Version 3.0 Physical Device Driver Reference. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSHJSCURDIRPREFIX 

Test for a prefix of a current directory 

Purpose 

This function allows FSDs to disallow any modification of any directory that is either 
a current directory of some process or the parent of any current directory of some 
process. This is necessary because the kernel manages the text of each current 
directory for each process. 

Calling Sequence 

int far pascal FSHJSCURDIRPREFIX (pName) 
char far \ pMsg; 


Where 

pName 

is a pointer to the path name. 

The name must be in canonical form, that is, no or components, upper- 
case, no meta characters, and full path name specified. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_CURRENT_DI RECTORY 

the specified path is a prefix of or is equal to the current directory of some 
process. 

If the current directory is the root and the path name is “d:\,” 
ERROR_CURRENT_DIRECTORY will be returned. 

Remarks 

FSHJSCURDIRPREFIX takes the supplied path name, enumerates all current 
directories in use, and tests to see if the specified path name is a prefix or is equal 
to some current directory. 

FSHJSCURDIRPREFIX may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_LOADCHAR 

Load a character from a string 

Purpose 

This function provides the mechanism for loading a character from a string, taking 
into account DBCS considerations. 

Calling Sequence 

void far pascal FSH_LOADCHAR (ppStr, pChar) 

char far Tar \ ppStr; 

unsigned short far \ pChar; 


Where 

ppStr 

is a pointer to the character pointer of a string. 

The character at this location will be retrieved and this pointer will be updated. 

pChar 

is a pointer to the character returned. 

If character is non-DBCS, the first byte will be the character and the second 
byte will be zero. 

Returns 

There are no error returns. 

Remarks 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_NAMEFROMSFN 

Get the full path name from an SFN. 

Purpose 

This call allows an FSD to retrieve the full path name for an object to which an 
SFN refers. 

Calling Sequence 

int far pascal FSHJS1AMEFROMSFN (sfn, pName, pcbName) 

unsigned short sfn; 

char far \ pName; 

unsigned short far \pcbName; 


Where 

sfn 

is the system file number of a file instance, obtained from the sfi_selfsfn field of 
the file-system-independent part of the SFT for the object. 

pName 

is the location of where the returned full path name is to be stored. 

pcbName 

is the location of where the FSD places the size of the buffer pointed to by 
pName. On return, the kernel will fill this in with the length of the path name. 
This length does not include the terminating null character. The size of the 
buffer should be long enough to hold the full path name, or else an error will be 
returned. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

EFtFtOFt_INVALID_HANDLE 

the SFN is invalid. 

E Ft FiO Ft_B U FFE Fi_0 VE Ft FLO W 

the buffer is too short for the returned path. 

Remarks 

FSFLNAMEFFtOMSFN will not block. 

Note: 

OS/2 does not validate input parameters; the FSD should call FSH_PROBEBUFF 
where appropriate. 
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FSH_PREVCHAR 
Decrement a character pointer 

Purpose 

This function provides the mechanism for decrementing a character pointer, taking 
into account DBCS considerations. 

Calling Sequence 

void far pascal FSH„PREVCHAR (pBeg, ppStr) 

char far \ pBeg; 

char far Tar \ ppStr; 


Where 

pBeg 

is a pointer to the beginning of a string. 

ppStr 

is a pointer to the character pointer of a string. 

The value is decremented appropriately upon return. If it is at the beginning of 
a string, the pointer is not decremented. If it points to the second byte of a 
DBCS character, it will be decremented to point to the first byte of the character. 

Returns 

There are no error returns. 

Remarks 

The FSD is responsible for verifying the string pointer and checking for segment 
boundaries. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PFiOBEBUF where appropriate. 
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FSH_PROBEBUF 

Check user address validity 

Purpose 

This function provides the mechanism for performing validity checks on arbitrary 
pointers to data that users may pass in. 

Note: FSDs must check on these pointers before using them. 

Calling Sequence 

int far pascal FSH_PROBEBUF (operation, pdata, cbData) 

unsigned short operation; 
char far \ pData; 

unsigned short cbData; 

Where 

operation 

indicates whether read or write access is desired. 

operation == PB_OPREAD, (0x00) indicates read access is to be checked, 
operation == PB_OPWRITE, (0x01) indicates write access is to be checked. 

All other values are reserved. 

pData 

is the starting address of user data. 

cbData 

is the length of user data. If cbData is 0, a length of 64K is indicated. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_PROTECTION_VIOLATION 

indicates access to the indicated memory region is illegal (access to the data is 
inappropriate or the user transfer region is partially or completely inaccessible). 

Remarks 

Because users may pass in arbitrary pointers to data, FSDs must perform validity 
checks on these pointers before using them. Because OS/2 is multi-threaded, the 
addressability of data returned by FSFI_PROBEBUF is only valid until the FSD 
blocks. Blocking, either explicitly or implicitly allows other threads to run, possibly 
invalidating a user segment. FSH_PROBEBUF must, therefore, be reapplied after 
every block. 

FSH_PROBEBUF provides a convenient method to assure a user transfer address 
is valid and present in memory. Upon successful return, the user address may be 
treated as a far pointer and accessed up to the specified length without either 
blocking or faulting. This is guaranteed until the FSD returns or until the next block. 

If FSH_PROBEBUF detects a protection violation, the process is terminated as 
soon as possible. The OS/2 kernel kills the process once it has exited from the 
FSD. 
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On 80386 processors, FSH_PROBEBUF ensures all touched pages are physically 
present in memory so the FSD will not suffer an implicit block due to a page fault. 
However, FSH_PROBEBUF does NOT guarantee the pages will be physically con- 
tiguous in memory because FSDs are not expected to do DMA. 

FSH_PROBEBUF may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_QSYSINFO 
Query system information 

Purpose 

This function queries the system about dynamic system variables and static system 
variables not returned by DosQSysinfo. 

Calling Sequence 

int far pascal FSFLQSYSINFO (index, pData, cbData) 

unsigned short index; 
char far \ pData; 

unsigned short cbData; 


Where 

index 

is the variable to return. 

index == QSLSECSIZE (0x01) indicates maximum sector size. This will be 
returned in an unsigned short field. 

index == QSLPROCID (0x02) indicates process identity. The data returned 
will be as follows: 

struct 

unsigned short PID; 
unsigned short UID; 
unsigned short PDB; 

index == QSLTHREADNO (0x03) indicates absolute thread number for the 
current thread. This will be returned in an unsigned short field. 

index == QSLVERIFY (0x04) indicates verify on write flag for the process. 
This will be returned in an unsigned char (byte) field. Zero means verify is 
off, non-zero means it is on. 

pData 

is the long address to the data area. 

cbData 

is the length of the data area. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_PARAMETER 

the index is invalid. 

ERROR_BUFFER_OVERFLOW 

the specified buffer is too short for the returned data. 
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Remarks 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_QUERYOPLOCK 

Query if the running thread has an oplock 

Purpose 

This function queries if the running thread has an oplock. 

Calling Sequence 

int far pascal FSH„QUERYOPLOCK (void) 


Returns 

This function returns as status indicator for whether the thread has an oplock or 
not. 

Oxffff - thread has an oplock 

0x0000 - thread does not have an oplock 
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FSH_QUERYSERVERTHREAD 

Query if the current thread is a server thread 

Purpose 

Query if the current thread is a server thread. 

Calling Sequence 

int far pascal F SH__QUERY SERVERTHRE AD (void) 

Returns 

This function returns a flag indicating whether the thread is a server thread. 
Oxffff - thread is a server thread 
0x0000 - thread is not a server thread 
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FSH_REGISTERPERFCTRS 
Register a FSD with PERFVIEW 

Purpose 

This function allows the FSD to register with the PERFVIEW product. The FSD 
passes pointers to its counter data and text blocks. 

Calling Sequence 

int far pascal FSHREGISTERPERFCTRS (pDataBlk , pTextBlk , fsFlags) 

void far \ pDataBlk; 

void far \ pTextBlk; 

unsigned short fsFlags; 

Where 

pDataBlk 

is a pointer to the data block where the actual counters reside. 

pTextBlk 

is a pointer to the block that contains instance and name information about 
counters in the associated DataBIk. 

fsFlags 

indicates what type of addressing is going to be used. 

RPC_16BIT (0x0000) indicates 16:16 pointers 
RPC_32BIT (0x0001) indicates 0:32 pointers 

All other bits are reserved and must be zero. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_PARAMETER 

the flag word is invalid. 

ERROR_PVW_INVALID_COUNTER_BLK 

the specified buffer is not in the correct PERFVIEW data block format 
ERROR_PVW_INVALID_TEXT_BLK 

the specified buffer is not in the correct PERFVIEW text block format 

Remarks 

For a detailed description of the PERFVIEW interface and its associated data 
structures please see the OS/2 Version 3.0 PERFVIEW OEMI Document. 

FSFLREGISTERPERFCTRS may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFI_PROBEBUF where appropriate. 
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FSH_REMOVESHARE 
Remove a shared entry 

Purpose 

This function removes a previously-entered name from the sharing set. 

Calling Sequence 

void far pascal FSH_REMOVE SHARE (hShare) 
unsigned long hShare; 


Where 

hShare 

is a share handle returned by a prior call to FSH_ADDSHARE. 

Returns 

There are no error returns. 

Remarks 

When a call to FSH_REMOVESHARE has been issued, the share handle is no 
longer valid. 

FSH_REMOVESHARE may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_SEGALLOC 

Allocate a GDT or LDT segment 

Purpose 

This function allocates a GDT or LDT selector. The selector will have read/write 
access. An FSD may call this function. 

Calling Sequence 

int far pascal FSH_SEGALLOC (flags, cbSeg, pSel) 

unsigned short flags; 

unsigned long cbSeg; 

unsigned short far \ pSel; 


Where 

flags 

indicate GDT/LDT, protection ring, swappable/non-swappable. 

Bit 0x0001 off indicates GDT selector returned. 

SA_FLDT (0x0001), bit 0x0001 on indicates LDT selector returned. 

Bit 0x0002 off indicates non-swappable memory. 

SA_FSWAP (0x0002), bit 0x0002 on indicates swappable memory. 

Bits 13 and 14 are the desired ring number. SA_FRINGMASK (0x6000) 
may be used to isolate it. 

All other bits are reserved and must be zero. 

cbSeg 

is the length of the segment. 

pSel 

is the far address of the location where the allocated selector will be stored. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERRORJNTERRUPT 

the current thread received a signal. 

ERROR_INVALID_PARAMETER 

the reserved bits in flags are set or requested size is too large. 
ERROR_NOT_ENOUGH_MEMORY 
too much memory is allocated. 

Remarks 

It is strongly suggested that FSDs allocate all their data at protection level 0 for 
maximum protection from user programs. 

GDT selectors are a scarce resource; the FSD must be prepared to expect an error 
for allocation of a GDT segment. The FSD should limit itself to a maximum of 10 
GDT segments. It is suggested that a large segment be allocated for each type of 
data and divided into per-process records. 
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FSH_SEGALLOC may block. 


Take care to avoid deadlocks between swappable segments and swapper requests. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PFiOBEBUF where appropriate. 
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FSH_SEGFREE 

Release a GDT or LDT segment 

Purpose 

This function releases a GDT or LDT segment previously allocated with 
FSH_SEGALLOC or loaded as part of the FSD image. 

Calling Sequence 

int far pascal FSH_SEGFREE (sel) 
unsigned short sel; 


Where 

sel 

is the selector to be freed. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_INVALID_ACCESS 

the selector is invalid. 

Remarks 

FSH_SEGFREE may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_SEGREALLOC 
Change segment size 

Purpose 

This function changes the size of a segment previously allocated with 
FSH_SEGALLOC or loaded as part of the FSD image. 

Calling Sequence 

int far pascal FSH_SEGRE ALLOC (sel, cbSeg) 

unsigned short sel; 
unsighed long cbSeg; 

Where 

sel 

is the selector to be changed. 

cbSeg 

is the new size to set for the segment. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_NOT_ENOUGH_MEMORY 

too much memory is allocated. 

ERROR_INVALID_ACCESS 

the selector is invalid 

Remarks 

The segment may be grown or shrunk. The segment may be moved in the 
process. When grown, the extra space is uninitialized. 

FSFLSEGREALLOC may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_SEMCLEAR 
Clear a semaphore 

Purpose 

This function allows an FSD to release a semaphore that was previously obtained 
on a call to FSH_SEMREQUEST. 

Calling Sequence 

int far pascal FSH_SEMCLEAR (pSem) 
void far \ pSem; 


Where 

pSem 

is the handle to the system semaphore or the long address of the ram 
semaphore. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_EXCL_ALREADY_OWNED 

the exclusive semaphore is already owned. 

ERROR_PROTECTION_VIOLATION 

the semaphore is inaccessible. 

Remarks 

FSH_SEMCLEAR may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_SEMREQUEST 
Request a semaphore 

Purpose 

This function allows an FSD to obtain exclusive access to a semaphore. 

Calling Sequence 

int far pascal FSH_SEMREQUEST (pSem, cmsTimeout) 

void far \ pSem; 

unsigned long cmsTimeout; 


Where 

pSem 

is the handle to the system semaphore or the long address of the ram 
semaphore. 

cmsTimeout 

is the number of milliseconds to wait. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERRORJNTERRUPT 

the current thread received a signal. 

ERROR_SEM_TIMEOUT 

the timeout expired without gaining access to the semaphore. 
ERROR_SEM_OWNER_DIED 
the owner of the semaphore died. 

ERROR_TOO_MANY_SEM_REQUESTS 
there are too many semaphore requests in progress. 
ERROR_PROTECTION_VIOLATION 
the semaphore is inaccessible. 

Remarks 

The timeout value of OxFFFFFFFF indicates an indefinite timeout. 


The caller may receive access to the semaphore after the timeout period has 
expired without receiving an ERROR_SEM_TIMEOUT. Semaphore timeout values, 
therefore, should not be used for exact timing and sequencing. 

FSFLSEMREQUEST may block. 

Note: The error, ERRORJNTERRUPT, is not usually a critical error. Unless the 
FSD needs to do some additional processing if a signal has occurred, it is normal 
to just retry the FSFLSEMREQUEST call. It is extremely important to check and 
handle the return codes for this call correctly. 
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Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_SEMSET 
Set a semaphore 

Purpose 

This function allows an FSD to set a semaphore unconditionally. 

Calling Sequence 

int far pascal FSH_SEMSET (pSem) 
void far \ pSem; 


Where 

pSem 

is the handle to the system semaphore or the long address of the ram 
semaphore. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERRORJNTERRUPT 

the current thread received a signal. 

ERROR_EXCL_SEM_ALREADY_OWNED 

the exclusive semaphore is already owned. 

ERROR_TOO_MANY_SEM_REQUESTS 

there are too many semaphore requests in progress. 

ERROR_PROTECTION_VIOLATION 

the semaphore is inaccessible. 

Remarks 

FSH_SEMSET may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_SEMSETWAIT 

Set a semaphore and wait for clear 

Purpose 

This function allows an FSD to wait for an event. The event is signalled by a call to 
FShLSEMCLEAR. 

Calling Sequence 

int far pascal FSH_SEMSETWAIT (pSem, cmsTimeout) 

void far \ pSem; 

unsigned long cmsTimeout; 


Where 

pSem 

is the handle to the system semaphore or the long address of the ram 
semaphore. 

cmsTimeout 

is the number of milliseconds to wait. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_SEM_TIMEOUT 

the timeout expired without gaining access to the semaphore. 
ERRORJNTERRUPT 
the current thread received a signal. 

ERROR_EXCL_SEM_ALREADY_OWNED 
the exclusive semaphore is already owned. 
ERROR_PROTECTION_VIOLATION 
the semaphore is inaccessible. 

Remarks 

The caller may return after the timeout period has expired without receiving an 
ERROR_SEM_TIMEOUT. Semaphore timeout values, therefore, should not be 
used for exact timing and sequence. 

FSFLSEMSETWAIT may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PROBEBUF where appropriate. 
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FSH_SEMWAIT 
Wait for clear 


Purpose 

This function allows an FSD to wait for an event. The event is signalled by a call to 
FShLSEMCLEAR. 

Calling Sequence 

int far pascal FSH_SEMWAIT (pSem, cmsTimeout) 

void far \ pSem; 

unsigned long cmsTimeout; 


Where 

pSem 

is the handle to the system semaphore or the long address of the ram 
semaphore. 

cmsTimeout 

is the number of milliseconds to wait. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_SEM_TIMEOUT 

the timeout expired without gaining access to the semaphore. 
ERRORJNTERRUPT 
the current thread received a signal. 

ERROR_PROTECTION_VIOLATION 
the semaphore is inaccessible. 

Remarks 

The caller may return after the timeout period has expired without receiving an 
ERROR_SEM_TIMEOUT. Semaphore timeout values, therefore, should not be 
used for exact timing and sequence. 

FSH_SEMWAIT may block. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSH_PROBEBUF where appropriate. 
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FSH_SETVOLUME 

Force a volume to be mounted on the drive 

Purpose 

This function provides the mechanism for assuring that a desired volume is in a 
removable media drive before I/O is done to the drive. 

Calling Sequence 

int far pascal F SH_SET V OLUME fhVPB , fControl) 

unsigned short hVPB; 

unsigned short fControl; 

Where 

hVPB 

is the volume handle for the source of I/O. 

fControl 

is the bit mask of pop-up control actions: 

Bit 0 off indicates volume change pop-up desired 
Bit 0 on indicates no volume change pop-up 
All other bits are reserved and must be zero. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_VOLUME_CHANGED 

is an indication that removable media volume change has occured. 
ERROR_INVALID_PARAMETER 
the fControl flag word has reserved bits on. 

Remarks 

This routine is used by the FSH_CALLDRIVER routine to insure that the desired 
volume is in a removable media drive. FSDs can use it for the same purpose. 

FSFLSETVOLUME may block. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFI_PROBEBUF where appropriate. 
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FSH_STACKSPACE 
Determin stack space 

Purpose 

Query if the current thread is a server thread. 

Calling Sequence 

int far pascal FSH_STACESPACE (pstackspace) 
unsigned long far pstackspace; 


Where 

pstackspace 

is a pointer to the available stack space. 

Returns 

Return available stack space. There are no error returns. 
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FSH_STORECHAR 

Store a character in a string 

Purpose 

This function provides the mechanism for storing a character into a string, taking 
into account DBCS considerations. 

Calling Sequence 

int far pascal FSH_STORECHAR (chDBCS, ppStr) 

unsigned short chDBCS; 
char far Tar \ ppStr; 

Where 

chDBCS 

is the character to be stored. This may be either a single-byte character or a 
double-byte character with the first byte occupying the low-order position. 

ppStr 

is the pointer to the character pointer where the character will be stored. This 
pointer is updated upon return. 

Returns 

There are no error returns. 

Remarks 

The FSD is responsible for verifying the string pointer and checking for segment 
boundaries. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFI_PFiOBEBUF where appropriate. 
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FSH_UPPERCASE 
Uppercase asciiz string 

Purpose 

This function is used to uppercase an asciiz string. 

Calling Sequence 

int far pascal FSHJJPPERCASE (szPathName, cbPathBuf, pPathBuf ) 

char far \ szPathName; 

unsigned short cbPathBuf; 
char far \ pPathBuf; 

Where 

szPathName 

is a pointer to the asciiz pathname to be uppercased. 

cbPathBuf 

is the length of the pathname buffer. 

pPathBuf 

is a pointer to the buffer to copy the uppercased path into 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, the 
following error code is returned: 

ERROR_BUFFER_OVERFLOW 

uppercased pathname is too long to fit into buffer. 

Remarks 

This routine processes DBCS characters properly. 

The FSD is responsible for verifying the string pointers and checking for segment 
boundaries. 

szPathName and pPathBuf may point to the same place in memory. 

FSFLUPPERCASE should be called for names passed into the FSD in raw data 
packets which are not passed to FSFLCANONICALIZE and should be uppercased, 
that is, extended attribute names. 

Note: OS/2 does not validate input parameters. Therefore, an FSD should call 
FSFLPROBEBUF where appropriate. 
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FSH_WILDMATCH 
Match using OS/2 wildcards 

Purpose 

This function provides the mechanism for using OS/2 wildcard semantics to form a 
match between an input string and a pattern, taking into account DBCS consider- 
ations. 

Calling Sequence 

int far pascal FSH_WILDMATCH (pPat, pStr) 

char far \ pPat; 
char far \ pStr; 


Where 

pPat 

is the pointer to an ASCIIZ pattern string. Wildcards are present and are inter- 
preted as described below. 

ppStr 

is the pointer to the test string. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, the 
following error code is returned: 

E R RO R_NO_M ET A_M AT C H 

the wildcard match failed. 

Remarks 

Wildcards provide a general mechanism for pattern matching file names. There are 
two distinguished characters that are relevant to this matching. The ’?’ character 
matches one character (not bytes) except at a or at the end of a string, where it 
matches zero characters. The matches zero or more characters (not bytes) with 
no implied boundaries except the end-of-string. 

For example, “a*b” matches “ab” and “aCCCCCCCCCb" while “a?b" matches “aCb” 
but does not match “aCCCCCCCCCb" 

See the section on meta characters in this document for additional information. 

The FSD should uppercase the pattern and string before calling FSH_WILDMATCH 
to achieve a case-insensitive compare. 

Note: OS/2 does not validate input parameters. An FSD, therefore, should call 
FSFLPFiOBEBUF where appropriate. 
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FSH_YIELD 

Yield processor to higher-priority thread 

Purpose 

This function provides the mechanism for relinquishing the processor to higher- 
priority threads. 

Calling Sequence 

void far pascal FSFLYIELD (void) 


Returns 

There are no error returns. 

Remarks 

FSDs run under the 2ms dispatch latency imposed on the OS/2 kernel, meaning 
that no more than 2ms can be spent in an FSD without an explicit block or yield. 
FSFI_YIELD will test to see if another thread is runable at the current thread’s pri- 
ority or at a higher priority. If one exists, that thread will be given a chance to run 
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Chapter 4. Remote IPL / Bootable IFS 

This chapter describes the OS/2 Version 3.0 boot architecture and extensions to 
the installable file system mechanism(IFSM) to enable booting from an 
FSD-managed volume, referred to as Bootable IFS(BIFS). If the volume is on a 
remote system, it is referred to as Remote IPL(RIPL). 

The mini-FSD is similar to the FSD defined in this document. However, it has addi- 
tional requirements for to allow reading of the boot drive before the base device 
drivers are loaded. These requirements are fully defined in the two interface 
sections of this chapter. 

To satisfy its I/O requests, the mini-FSD may call the disk device device driver 
imbedded in OS2KRNL(BIFS case) or it may provide its own driver(RIPL case). 

Along with the mini-FSD, the IFS SYS Utility is required to initialize an 
FSD-managed volume with whatever is required to satisfy the requirements of the 
mini-FSD and this document. 

The IFS mechanism includes some additional calls which the mini-FSD may need 
while it is linked into the IFS chain. 
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Operational Description 


FAT Boot Procedure 

The following figure represents the major stages of the OS/2 Version 3.0 FAT boot 
procedure. 


♦UUUUUUUUUU»UUUUUUUUUU4UUUUUUUUUU»UUUUUUUUUU»UUUUUUUUUU»UUUUUUUUUU*UUUUUUUUUUi 
POST BOOT OS2BOOT OS2LDR stage 1 stage2 stage3 

SECTOR (OS2LDR OS2KRNL 

loader) 

Figure 4-1. OS/2 Version 3.0 FAT boot procedure 

Powering-on the machine or pressing CTRL-ALT-DEL causes control to get trans- 
ferred to the power-on-self-test (POST) code. This code initializes the interrupt 
vectors to get to the BIOS routines. It then scans the I/O adapters looking for and 
linking in any code which exists on them. It then executes an interrupt 19h (INT 
19) which causes control to be transferred to the disk or diskette boot code. 

The INT 19h code reads the boot sector from disk or diskette into memory at 
7C00H. Along with code, the boot sector contains a structure called the BIOS 
Parameter Block(BPB). The BPB contains information which describes how the 
disk is formatted. The boot code uses this information to load in the root directory 
and the FAT micro-IFS, which is kept inside the OS2BOOT file. After the micro-IFS 
is loaded the boot sector transfer control it via a far jump. 

OS2BOOT receives pointers to the RAM copies of the root directory and the BPB. 

Using the BPB information, OS2BOOT loads in the FAT table from the disk. Then 
using the root directory and the FAT table, the OS2LDR file is loaded into memory 
from disk. The inclusion of this micro-IFS in the FAT boot process has removed 
the requirement that the OS2LDR file be logically contigous on the FAT drive. 

OS2LDR contains the OS/2 loader. It relocates itself to the top of low memory, 
then scans the root directory for OS2KRNL and reads it into memory. After the 
required fixups are applied, control is transferred to OS2KRNL, along with a pointer 
to the BPB and the drive number. 

OS2KRNL contains the OS/2 kernel and initialization code. It switches to protected 
mode, relocates parts of itself to high memory, then scans the root directory for and 
reads in the base device drivers (stage 1). Once again, the BIOS interrupt 13h is 
used to read the disk, but mode switching must be done. 

OS2KRNL then switches to protection level 3 and loads some of the required 
dynamic link libraries (stage 2) followed by the device drivers and FSDs specified in 
CONFIG.SYS (stage 3). This is done with standard DOS calls and, therefore, goes 
through the regular file system and device drivers. 
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BIFS Boot Procedure 

The following figure represents the major stages of the OS/2 Version 3.0 BIFS boot 
procedure. 


♦UUUUUUUUUU»UUUUUUUUUU4UUUUUUUUUU»UUUUUUUUUU»UUUUUUUUUU»UUUUUUUUUU^ time 
POST BlackBox OS2LDR stage 1 stage2 stage3 
(Micro OS2KRNL 

FSD) 

Figure 4-2. OS/2 Version 3.0 BIFS boot procedure 

The major difference between this boot procedure and the FAT boot procedure is 
that there is no assumption of booting off of disk. OS/2 Version 3.0 does not define 
what should happen between when the POST code is run and when the OS2LDR 
program gains control. 

When OS2LDR receives control, it must be passed information about the current 
state of memory and pointers to the Open, Read, Close, and Terminate entry points 
of the micro-FSD. Included in the memory map information is the positions of the 
micro-FSD, mini-FSD, RIPL data, and the OS2LDR file itself. 

Note: This interface is defined in a next section of this chapter. 

As with the FAT boot procedure, the OS/2 loader relocates itself to the top of low 
memory, and with the help of the micro-FSD, scans the root directory for the 
OS2KRNL file. After reading OS2KRNL into memory and applying the required 
fixups, control is transferred to the kernel. 

When OS2KRNL receives control, it goes through the same initialization as before 
(stage 1) with a couple of exceptions. The module loader is called to load the 
mini-FSD from its memory image stored by OS2LDR in high memory to its final 
location at the top of low memory. Also, the mini-FSD is called to read the base 
device drivers (one at a time) through the stage 1 interfaces. 

Before any of the dynalinks are loaded, the mini-FSD will be linked into the IFS 
chain (it will be the only link in the chain) and asked to initialize through FSJNIT. 

The FSJNIT call marks the transition from stage 1 to stage 2. 

The dynalinks are then loaded using the stage 2 interfaces, followed by the device 
drivers and FSDs. 

The mini-FSD is required to support only a small number of the FSD system inter- 
faces (the FS_xxxx calls). Therefore, the first FSD loaded must be the replacement 
for the mini-FSD. 

After the replacement FSD has been loaded, it is called at FSJNIT to initialize itself 
and take whatever action it needs to effect a smooth transition from the mini-FSD 
to the FSD. It then replaces the mini-FSD in the IFS chain, as well as in any kernel 
data structures which keep a handle to the FSD (for example, the SFT, VPB). This 
replacement marks the transition from stage 2 to stage 3. 

From this point on, the system continues normally. 
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Interfaces 


BlackBox/OS2LDR interface 

When initially transferring control to OS2LDR from a "black box", the following inter- 
face is defined: 

DH 

boot mode flags: 

bit 0 (NOVOLIO) on indicates that the mini-FSD does not use 
mFSH_DOVOLIO. 

bit 1 (RIPL) on indicates that boot volume is not local (RIPL boot) 
bit 2 (MINIFSD) on indicates that a mini-FSD is present, 
bit 3 (RESERVED) 

bit 4 (MICROFSD) on indicates that a micro-FSD is present, 
bits 5-7 are reserved and MUST be zero. 


DL 

drive number for the boot disk. This parameter is ignored if either the NOVOLIO 
or MINIFSD bits are zero. 

DS.SI 

is a pointer to the BOOT Media's BPB. This parameter is ignored if either the 
NOVOLIO or MINIFSD bits are zero. 

ES:DI 

is a pointer to a filetable structure. The filetable structure has the following 
format: 


struct FileTable { 

unsigned short ft_cfiles; A# of entries in this table X 

unsigned short ft_ldrseg; Aparagraph # where OS2LDR is loaded X 
unsigned long ft_ldrlen; A length of OS2LDR in bytes X 

unsigned short ft_museg; Aparagraph # where microFSD is loaded X 
unsigned long ft_mulen; Alength of microFSD in bytes X 

unsigned short ft_mfsseg; Aparagraph # where miniFSD is loaded X 
unsigned long ft_mfslen; Alength of miniFSD in bytes X 

unsigned short ft_ripseg; Aparagraph # where RIPL data is loaded X 
unsigned long ft_riplen; A length of RIPL data in bytes X 

AThe next four elements are pointers to microFSD entry points X 

unsigned short (far Ft_muOpen) 

(char far )aName, unsigned long far (oulFileSize); 
unsigned long (far ft_muRead) 

(long loffseek, char far ^Buf, unsigned long cbBuf); 
unsigned long (far ft_muClose)(void); 
unsigned long (far Ft_muTerminate)(void); 

} 


The microFSD entry points interface is defined as follows: 


mu_Open - is passed a far pointer to name of file to be opened and 
a far pointer to a ULONG to return the file's size. The 
returned valuefin AX) indicates success(Q) or failure(non-G). 

mu_Read - is passed a seek offset, a far pointer to a data buffer, 

and the size of the data buffer. The returned value(in DX:AX) 


4-4 DRAFT: OS/2 Installable File Systems 



indicates the number of bytes actually read. 


mu_Close - has no parameters and expects no return value. It is a signal 
to the micro-FSD that the loader is done reading the current 
file. 

mu_Terminate - has no parameters and expects no return value. It is a 
signal to the micro-FSD that the loader has finished reading 
the boot drive. 


The loader will call the micro-FSD in a Open-Read-Read-. ...-Read-Close sequence 
with each file read in from the boot drive. 

miniFSD/OS2KRNL interface 

When called from OS2KRNL after being linked into the IFS chain, the interface will 
be as described in previous chapters of this document. Note that the FSJNIT inter- 
face for a mini-FSD has an additional parameter, as compared to the FSJNIT inter- 
face for an FSD. 

When called from OS2KRNL, before being linked into the IFS chain, the interface 
will be through the MFS_xxxx and MFSFI_xxxx entry points. These interfaces are 
described in this chapter. Many of these interfaces parallel the interfaces defined 
for FSDs, while others are unique to the mini-FSD. 

The mini-FSD is built as a dynamic link library. Supplied functions are exported by 
making the function names public. Helper functions are imported by declaring the 
helper names externakfar. It is required only to support reading files and will be 
called only in protect mode. The mini-FSD may NOT make dynamic link system 
calls at initialization time. 

Due to the special state of the system as it boots, the programming model for the 
mini-FSD during the state 1 time frame is somewhat different than the model for 
stage 2. This difference necessitates 2 different interfaces between OS/2 and the 
mini-FSD. 

During stage 1, all calls to the mini-FSD are to the MFS_xxxx functions. Only the 
MFSH_xxxx helper functions are available. These are the interfaces which are 
addressed in this document. Many of these interfaces parallel the interfaces 
defined for FSDs while others are unique to the mini-FSD. 

During stage 2, the mini-FSD is treated as a normal FSD. Calls are made to the 
FS_xxxx functions and all FSH_xxxx helper functions are available. 

During stage 3, the mini-FSD is given a chance to release resources (through a call 
to MFS_TERM) before being terminated. 

Transition from stage 1 to stage 2 is marked by calling the FSJNIT function in the 
mini-FSD. Transition from stage 2 to stage 3 is marked by calling FSJNIT in the 
FSD. 

Figure 4-3 on page 4-6 shows the functions called during a typical boot sequence: 
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♦ UUUUUUUUUUUUUUUUUUUUiUUUUUUUUUUUUUUUUUUUUilJUUUUUUUUUUUUUUUUUULV time 
stage 1 stage 2 stage 3 

MFSJNIT 

MFS_OPEN 

MFS_READ 

MFS_CHGFILEPTR 

MFS_CLOSE 


FSJNIT 

FS_MOUNT/ATTACH 

FS_OPEN 

FS_READ 

FS_CHGFILEPTR 


MFS_TERM 


Figure 4-3. Typical boot sequence 

No files are open at the transition from stage 1 to stage 2. Also, only a single file 
at a time is open during stage 1. Files and volumes are open during the transition 
from stage 2 to stage 3 (the mini-FSD to the FSD). The FSD must do whatever is 
necessary for it to inherit them. The FSD will not receive mounts/attaches or opens 
for volumes and files which were mounted/attached and opened by the mini-FSD. 
Also, multiple files may be open simultaneously during stages 2 and 3. 

A special set of helper functions are available to the mini-FSD to support an 
imbedded device driver. This might be required for situations such as remote IPL 
where the boot volume is not readable through DOVOLIO. These special helper 
functions (referred to as imbedded device driver helpers) are available during all 
stages of the mini-FSD's life. Note that the list of error return codes for the helper 
functions is not exhaustive, but rather represents the most common errors returned. 

Because the mini-FSD is a new component added to the boot sequence, a new 
interface to OS2LDR is required. 

The name and attributes of the mini-FSD must match EXACTLY the name and 
attributes of the replacement FSD. 

Due to the instability of the system during initialization, any non-zero return code 
indicates an error has been encountered. The actual return code may not bake 
any sense in the context of the function called (for example, having 
ERROR_ACCESS_DENIED returned from a call to MFSH_LOCK when in fact an 
invalid selector was passed to the helper). It is also possible for the system to 
hang or reboot itself as a result of invalid parameters being passed to a helper 
function. 

Stage 1 Interfaces 

The following functions must be made available by the mini-FSD. These functions 
will be called only during stage 1 . 

MFS_CHGFILEPTR 

MFS_CLOSE 

MFSJNIT 
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MFS_OPEN 

MFS_READ 

MFS_TERM 

The following helper functions are available to the mini-FSD. These functions may 
be called only during stage 1. 

MFSFLDOVOLIO 
MFSHJNTERR 
MFSFLS EG ALLOC 
MFSFLSEGFREE 
MFSFLS EG RE ALLOC 

Stage 2 Interfaces 

The intent of stage 2 is to use the mini-FSD as an FSD. Therefore, all the guide- 
lines and interfaces specified in this document apply with the following exceptions. 

The following functions must be fully supported by the mini-FSD: 

FS_ATTACH (remote mini-FSD only) 

FS_ATTRIBUTE 

FS_CHGFILEPTR 

FS_CLOSE 

FS_COMMIT 

FSJNIT 

FSJOCTL 

FS_MOUNT (local mini-FSD only) 

FS_NAME 

FS_OPENCREATE (existing file only) 

FS_PROCESSNAME 

FS_READ 

Note that since the mini-FSD is only required to support reading, 
FS_OPENCREATE need only support opening an existing file (not the create or 
replace options). 

None of the other functions required for FSDs are required for the mini-FSD but 
must be defined and should return the ERROR_UNSUPPORTED_FUNCTION 
return code. 

The full complement of helper functions specified in this document is available to 
the mini-FSD. However, the mini-FSD may NOT use any other dynamic link calls. 

Stage 3 Interfaces 

The intent of stage 3 is to throw away the mini-FSD and use only the FSD. 

The following functions must be supported by the mini-FSD: 

MFS_TERM 
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Imbedded Device Driver Helpers 

The following helper functions are available to the mini-FSD and may be called 
during stage 1 , 2, or 3. These helpers are counterparts for some of the device help 
functions and are intended for use by a device driver imbedded within the 
mini-FSD. 


MFSH_CALLRM 

MFSFLLOCK 

MFSFLPHYSTOVIRT 

MFSFIJJNLOCK 

MFSHJJNPHYSTOVIRT 

MFSH_VIRTTOPHYS 
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Special Considerations 

The size of the mini-FSD file image plus the RIPL data area may not exceed 62K. 

In addition, the memory requirements of the mini-FSD may not exceed 64K. 

The mini-FSD is only required to support reading of a file. Therefore, any call to 
DosWrite (or other non-supported functions) which becomes redirected to the 
mini-FSD may be rejected. For this reason, it is required that the IFS= command 
which loads the FSD which will replace the mini-FSD be the first IFS= command in 
CONFIG.SYS. Also, only DEVICE= commands which load device drivers required 
by that FSD should appear before the first IFS= command. 

If the mini-FSD needs to switch to real mode, it must use the MFSFLCALLRM func- 
tion. This is required to keep OS/2 informed of the mode switching. 

Each FSD which is bootable is required to provide their "black box" to load 
OS2LDR and the mini-FSD into memory before OS2LDR is given control. 

Additionally, these FSDs are required to provide a single executable module in 
order to support the OS/2 SYS utility. The executable provided will be invoked by 
this utility when performing a SYS for that file system. The command line that was 
passed to the utility will be passed unchanged to the executable. 

The supplied executable must do whatever is required to make the partition 
bootable. At the very least, it must install a boot sector. It also needs to install the 
"black box", mini-FSD, OS2LDR and OS2KRNL. 
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mini-FSD Entry Points 

The following table is a summary of mini-FSD entry points: 


Table 4-1. Summary of mini-FSD entry points 

Entry Point Description. 


MFS.CHGFILEPTR 

MFS„CLOSE 

MFSJNIT 

MFSJDPEN 

MFS_READ 

MFS^TERM 


Move a file's position pointer 
Close a file. 
mini-FSD initialization 
Open a file 
Read from a file 
Terminate the mini-FSD 
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MFS_CHGFILEPTR 

Move a file's position pointer 

Purpose 

Move the file's logical read position pointer. 

Calling Sequence 

int far pascal MFS_CHGFILEPTR (offset, type) 

long offset; 

unsigned short type; 


Where 

offset 

is the signed offset which depending on the type parameter is used to determine 
the new position within the file. 

type 

indicates the basis of a seek operation. 

type == 0 indicates seek relative to beginning of file. 

type == 1 indicates seek relative to current position within the file. 

type == 2 indicates seek relative to end of file. 

Remarks 

The file system may want to take the seek operation as a hint that an I/O operation 
is about to take place at the new position and initiate a positioning operation on 
sequential access media or read-ahead operation on other media. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 

Remarks 

None 
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MFS_CLOSE 
Close a file 


Purpose 

Close a file. 

Calling Sequence 

int far pascal MFS_CLOSE (void) 


Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 

Remarks 

None 
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MFSJNIT 

mini-FSD Initialization 

Purpose 

Inform the mini-FSD that it should prepare itself for use. 

Calling Sequence 

int far pascal MFSJNIT (pBootData , pucResDrives , pulVectorlPL, 

pBPB , pMiniFSD , pDumpAddr) 


void far \ pBootData; 

char far \ pucResDrives; 

long far \ pulVectorlPL; 

void far \ pBPB; 

unsigned long far \ pMiniFSD; 
unsigned long far \pDumpAddr; 


Where 

pBootData 

is a pointer to the data passed from the black box to the mini-FSD(null if not 
passed). 

pucResDrives 

is a pointer to a byte which may be filled in by the mini-FSD with the number of 
drive letters (beginning with 'C') to skip over before assigning drive letters to 
local fixed disk drivers (ignored if not remote IPL). The system will attach the 
reserved drives to the mini-FSD through a call to FS_ATTACFI just after the call 
to FSJNIT. 

pulVectorlPL 

is a pointer to a double word which may be filled in by the mini-FSD with a 
pointer to a data structure which will be available to installable device drivers 
through the standard device helper function GetDosVar(variable number 12). 
The first eight bytes of the structure MUST be a signature which would allow 
unique identification of the data by cooperating device drivers (for example, 
IBMPCNET). 

BPB 

is a pointer to the BPB data structure (see OS2LDR interface). 

pMiniFSD 

is a pointer to a double word which is filled in by the mini-FSD with data to be 
passed on to the FSD. 

DumpRoutine 

is a pointer to a double word which is filled in by the mini-FSD with the address 
of an alternative stand-alone dump procedure. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 
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Remarks 

The mini-FSD should fill in the data pointed to by pMiniFSD with any 32-bit value it 
wishes to pass on to the FSD (see FSJNIT). OS/2 makes no assumptions about 
the type of data passed. Typically, this will be a pointer to important data struc- 
tures within the mini-FSD which the FSD needs to know about. 

OS/2 will not free the segment containing BootData. It should be freed by the 
mini-FSD if appropriate. 

The DumpProcedure is a routine provided by the mini-FSD which replaces the 
diskette-based OS/2 stand-alone dump procedure. This routine is given control 
after the OS/2 kernel receives a stand-alone dump request. The OS/2 kernel 
places the machine in a stable, real mode state in which most interrupt vectors 
contain their original power-up value. If this address is left at zero, the OS/2 kernel 
will attempt to initiate a storage dump to diskette, if a diskette drive exists. The 
provided routine must handle the dumping of storage to an acceptable media. 
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MFS_OPEN 
Open a file 


Purpose 

Open the specified file. 

Calling Sequence 

int far pascal MFS_OPEN (pszName , pulSize) 

char far \ pszName; 

unsigned long far \ pulSize; 


Where 

pszName 

is a pointer to the ASCIIZ name of the file to be opened. It may include a path 
but will not include a drive. 

pulSize 

is a pointer to a double word which is filled in by the mini-FSD with the size of 
the file in bytes. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 

Remarks 

Only one file at a time will be opened by this call. The drive will always be the boot 
drive. 

The current file position is set to the beginning of the file. 
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MFS_READ 
Read from a file 


Purpose 

Read the specified number of bytes from the file to a buffer location. 

Calling Sequence 

int far pascal MFS„READ (pcData , pusLength) 

char far \ pcData; 

unsigned long far \ pusLength; 


Where 

pcData 

is a pointer to the data area to be read into. The data area is guaranteed to be 
below the 1-Meg boundary. 

pusLength 

is a pointer to a word which on entry specifies the number of bytes to be read. 
On return, it is filled in by the mini-FSD with the number of bytes successfully 
read. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 

Remarks 

The current file position is advanced by the number of bytes read. 
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MFS_TERM 

Terminate the mini-FSD 

Purpose 

Inform the mini-FSD that it should prepare itself for termination. 

Calling Sequence 

int far pascal MFS_TERM (void) 


Returns 

If no error is detected, a zero error code is returned. If an error is detected, a 
non-zero erro code is returned. 

Remarks 

The system will NOT free any memory explicitly allocated by the mini-FSD through 
MFSH_SEGALLOC or FSFLSEGALLOC. It must be explicitly freed by the 
mini-FSD. (Memory allocated by the mini-FSD and 'given' to the FSD need not be 
freed.) The system will free all of the segments loaded as part of the mini-FSD 
image immediately after this call. 
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mini-FSD Helper Routines 

The following table summaries the mini-FSD Helper Routines: 


Table 4-2. Summary of mini-FSD Helpers 

FSD Helper Description 


MFSH_CALLRM 

MFSH_DOVOLIO 

MFSHJNTERR 

MFSH_LOCK 

MFSH_PHYSTOVIRT 

MFSH_SEGALLOC 

MFSH_SEGFREE 

MFSH_SEGREALLOC 

MFSH_SETBOOTDRIVE 

MFSHJJNLOCK 

MFSHJJNPHYSTOVIRT 

MFSH_VIRT2PHYS 


Put machine in real mode 
Read sectors 
Internal error 
Lock segment 

Convert physical to virtual address 
Allocate a segment 
Free a segment 
Change segment size 

Change boot drive number kept by the OS/2 kernel 
Unlock a segment 

Mark completion of use of virtual address 
Convert virtual to physical address 
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MFSH_CALLRM 

Put machine in real mode 

Purpose 

Put the machine into real mode, call the specified routine, put the machine back 
into protect mode, and return. 

Calling Sequence 

int far pascal MFSH_CALLRM (plRoutine) 
unsigned long far \ plRoutine; 


Where 

plRoutine 

is a pointer to a double word which contains the VIRTUAL address of the 
routine to call. 

Returns 

There are no error returns. 

Remarks 

Only registers DS and SI will be preserved between the caller and the target 
routine. The selector in DS will be converted to a segment before calling the target 
routine. Arguments may not be passed on the stack since a stack switch may 
occur. 

This helper allows the mini-FSD to access the ROM BIOS functions which typically 
run in real mode only. Great care must be taken in using this function since selec- 
tors used throughout the system are meaningless in real mode. While in real 
mode, no calls to any helpers may be made. 
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MFSH_DOVOLIO 
Read sectors 


Purpose 

Read the specified sectors. 

Calling Sequence 

int far pascal MFSFLDOVOLIO fpcData , pcSec , ulSec) 

char far \ pcData; 

unsigned short far \ pcSec; 
unsigned long ulSec; 


Where 

pcData 

is a pointer to the data area. The data area must be below the 1-Meg 
boundary. 

pcSec 

is a pointer to the word which specifies the number of sectors to be read. On 
return, it is filled in by the helper with the number of sectors successfully read. 

ulSec 

is the sector number for the beginning of the sector run. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied address or length is invalid. 

ERROR_INVALID_FUNCTION 

either bit 0 of the boot mode flags was set on entry to OS2LDR or the system 
is not in stage 1 . 

Remarks 

The only media which can be read by this call is the boot volume. The machine's 
interrupt 13H BIOS function is used to actually do the disk reads. The data area 
will be locked and unlocked by this helper. Soft errors are retried automatically. 
Hard errors are reported to the user through a message and the system is stopped. 
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MFSHJNTERR 
Internal Error 


Purpose 

Declare an internal error and halt the system. 

Calling Sequence 

int far pascal MFSHJNTERR (pcMsg , cbMsg) 

char far \ pcMsg; 

unsigned short cbMsg; 


Where 

pcMsg 

is a pointer to the message text. 

cbMsg 

is the length of the message text. 

Returns 

There are no error returns. 

Remarks 

This call should be used when an inconsistency is detected within the mini-FSD. 
This call does not return. An error message will be displayed and the system will 
be stopped. See the description of FSHJNTERR. 
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MFSH_LOCK 
Lock a segment 

Purpose 

Lock a segment in place in physical memory. 

Calling Sequence 

int far pascal MFSLLLOCK (usSel , pulHandle) 

unsigned short usSel; 

unsigned long far \pulHandle; 


Where 

usSel 

is the selector of the segment to be locked. 

pulHandle 

is a pointer to a double word which is filled in by the helper with the lock handle. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied address or selector is invalid. 

Remarks 

This helper is for use by a mini-FSD with an imbedded device driver. It is the same 
as the standard device driver LOCK helper with the following assumptions: The 
lock is defined to be short term and will block until the segment is loaded. 
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MFSH_PHYSTOVIRT 

Convert physical to virtual address 

Purpose 

Translate the physical address of a data buffer into a virtual address. 

Calling Sequence 

int far pascal MFSHPHYSTOVIRT (ulAddr , usLen , pusSel) 

unsigned long ulAddr; 

unsigned short usLen; 

unsigned short far \pusSel; 


Where 

ulAddr 

is the physical address to be translated. 

usLen 

is the length of the segment for the physical address. 

pusSel 

is a pointer to the word in which the selector or segment is returned. 

Returns 

If an error is not detected, a zero error code is returned. If an error is detected, the 
following error is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied address is invalid. 

Remarks 

This helper is for use by a mini-FSD with an imbedded device driver. It is the same 
as the standard device driver helper PHYSTOVIRT. A segment/offset pair is 
returned in real mode for addresses below 1 mb. Else a selector/offset pair is 
returned. 

A caller must issue a corresponding UNPHYSTOVIRT before returning to its caller 
or using any other helpers. 
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MFSH_SEGALLOC 
Allocate a segment 

Purpose 

Allocate memory. 

Calling Sequence 

int far pascal MFSH_SEGALLOC (usFlag , cbSeg , pusSel) 

unsigned short usFlag; 

unsigned long cbSeg; 

unsigned short far \pusSel; 


Where 

usFlag 

is set to 1 if the memory must be below the 1-meg boundary or 0 if its location 
does not matter. 

cbSeg 

contains the length of the segment. 

pusSel 

is a pointer to a word in which the helper returns the selector of the segment. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, one of 
the following error codes is returned: 

ERROR_NOT_ENOUGH_MEMORY 

too much memory is allocated. 

ERROR_PROTECTION_VIOLATION 

the supplied address is invalid. 

ERROR_INVALID_PARAMETER 

either the supplied flag or length is invalid. 

Remarks 

This function allocates memory with the following attributes: 

Allocated from the GDT 
Non-swappable 

Memory not allocated specifically below the 1-Meg boundary may be given to the 
FSD by passing the selectors through pMiniFSD (see MFSJNIT and FSJNIT). 
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MFSH_SEGFREE 
Free a segment 


Purpose 

Free a memory segment. 

Calling Sequence 

int far pascal MFSH_SEGFREE (usSel) 
unsigned short usSel; 


Where 

usSel 

contains the selector of the segment to be freed. 

Returns 

If no error is detected, a zero error error code is returned. If an error is detected, 
the following error code is returned: 

ERROR_PROTECTION_VIOLATION 

the selector is invalid. 

Remarks 

This function releases a segment previously allocated with MFSH_SEGALLOC, or 
loaded as part of the mini-FSD image. 


Chapter 4. Remote IPL / Bootable IFS 


4-25 



MFSH_SEGREALLOC 
Change segment size 

Purpose 

Change the size of memory. 

Calling Sequence 

int far pascal MFSH_SEGREALLOC (usSel , cbSeg) 

unsigned short usSel; 

unsigned long cbSeg; 


Where 

usSel 

contains the selector of the segment to be resized. 

cbSeg 

contains the new length of the segment. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, on of 
the following error codes is returned: 

ERROR_NOT_ENOUGH_MEMORY 

too much memory is allocated. 

ERROR_PROTECTION_VIOLATION 

the supplied selector is invalid. 

ERROR_INVALID_PARAMETER 

the supplied length is invalid. 

Remarks 

This call changes the size of a segment previously allocated with 
MFSH_SEGALLOC, or loaded as part of the mini-FSD image. 

The segment may be grown or shrunk. When grown, the extra space is uninitial- 
ized. The segment may be moved in the process. 
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MFSH_SETBOOTDRIVE 

Change boot drive number kept by the OS/2 kernel 

Purpose 

Change boot drive number kept by the kernel to allow a change in the assignment 
of boot drive as seen by later processes. 

Calling Sequence 

int far pascal MFSH_SETBOOTDRIVE (usDrive) 
unsigned short usDrive; 


Where 

usDrive 

contains the 0-based drive number that the mini-FSD wants the system to con- 
sider as the boot drive. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, on of 
the following error codes is returned: 

ERROR_INVALID_PARAMETER 

the supplied drive number is invalid. 

Remarks 

This call changes the boot drive number that is kept in the global info segment of 
the system. Valid values range from 2(=C) to 25(=Z). This function must be called 
during the call to MFSJNIT to update the info segment correctly. This is routine 
should be used by RIPL mini-FSDs. 
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MFSH_UNLOCK 
Unlock a segment 

Purpose 

Unlock a segment which was previous locked by calling MFSH_LOCK. 

Calling Sequence 

int far pascal MFSH_SEGREALLOC (ulHandle) 
unsigned long ulHandle; 


Where 

ulHandle 

contains the handle returned from MFSH_LOCK of the segment to unlock. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, the 
following error code is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied address is invalid. 

Remarks 

This helper is for use by a mini-FSD with an imbedded device driver. It is the same 
as the standard device driver helper UNLOCK. 
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MFSH_UNPHYSTOVIRT 

Mark completion of use of virtual address 

Purpose 

Release the selector allocated previously by calling MFSH_PHYSTOVIRT. 

Calling Sequence 

int far pascal MFSHUNPHYSTOVIRT (usSel) 
unsigned short usSel; 


Where 

usSel 

contains the selector to released. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, the 
following error code is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied selector is invalid. 

Remarks 

This helper is for use by a mini-FSD with an imbedded device driver. It is the same 
as the standard device driver UNPFIYSTOVIRT helper. 

A caller must issue a corresponding UNPFIYSTOVIRT after calling PHYSTOVIRT, 
before returning to its caller or using any other helpers. 
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MFSH_VIRT2PHYS 

Convert virtual to physical address 

Purpose 

Translate the address of a data buffer into a physical address. 

Calling Sequence 

int far pascal MFSH_VIRT2PHYS (ulVirtAddr , pulPhysAddr) 

unsigned long ulVirtAddr; 

unsigned long far \pulPhysAddr; 


Where 

ulVirtAddr 

contains the virtual address of the data area. 

PhysAddr 

is a pointer to a double word in which the helper returns the physical address of 
the data area. 

Returns 

If no error is detected, a zero error code is returned. If an error is detected, the 
following error is returned: 

ERROR_PROTECTION_VIOLATION 

the supplied address is invalid. 

Remarks 

This helper is for use by a mini-FSD with an imbedded device driver. It is the same 
as the standard device driver helper VIRTTOPHYS. 


4-30 


DRAFT: OS/2 Installable File Systems 



Chapter 5. Index 


A 

access to EAs, controlling 1-11 
allocate segment 3-41 
API, extended file I/O 1-4 
API, standard file I/O 1-2 
attach to an FSD 2-4 
attributes, FSDs. 1-12 

B 

BIFS 4-1 

BIFS boot procedure 4-3 
boot partition 1 -6 
boot procedure 4-3 
boot sector 4-2 
bootable IFS 4-1 
BPB 4-2 

buffer management 1-5 

c 

caching 1-5 

calling conventions, FSDs 1-22 
cancel file lock request 2-6 
canonicalization 2-72, 3-7 
cdfsd, current directory parameters 1-20 
cdfsi, current directory parameters 1-20 
CDS 1-19 

change/verify directory path 2-7 
character pointer 3-32 
character validation 1-10 
CHKDSK 1-7 
clear semaphore 3-45 
close a file 2-12 

commit a file's buffers to disk 2-13 
commit file buffers 2-46 
CONFIG.SYS statements 1-6 
CONFIG.SYS, IFS= 1-13 
copy a file 2-15 
CPU time 1-22 

current directory parameters, cdfsd 1-20 
current directory parameters, cdfsi 1-20 
current directory prefix 3-29 
current directory structure 1-19 
current directory, data structures 1-20 


current I/O priority, boost 3-27 
current I/O priority, determine 3-24 

D 

Data Structures, FSD 
current directory 1-20 
disk media and file system layout 1-19 
file search records 1-21 
open files 1-20 
timestamps 1-22 
data structures, FSDs 1-19 
data, file-system-dependent 1-19 
data, file-system-independent 1-19 
date, format of 1-17 
delete a file 2-17 
device I/O control 2-52 
directory search, begin 2-33 
directory search, continue 2-39 
directory search, end 2-32 
disk media and file system layout 1-19 
disk partitions 1-6 
DOS partition 1-6 
DosDevlOCtl 2-52 
DosFsCtl 1-4 
DosOpen 2-65 
DosQFsAttach 1-7 
DosQFSInfo 2-50 
DosQPathlnfo 2-71 
DosQSysInfo 2-72 
DosSetFSInfo 2-50 
DosSetPathlnfo 2-71 
DPB 1-5 

drive parameter block 1-5 
drives and file systems 1-5 

E 

EA manipulation 1-11 
EA name validity 3-9 
EAOP 1-11 
end of process 2-20 
entry points, FSDs (summary) 2-1 
error return codes, file I/O 1-17 
extend thread's time slice 3-19 
Extended Attributes 
EA name validity 3-9 
FAT file system 1-11 
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Extended Attributes (continued) 

FEAs 1-9 
GEAs 1-10 

extended boot structure 1-14 
extended file API 2-47 
extended file I/O API 1-4 
Extended strategy call 3-5 

F 

family API 1-7 
FAT file system 1-5 
FAT partition 1-6 
FEAlist 1-10 
FEAs 1-9 
features, IFS 1-1 
file access, lock 2-29 
file access, unlock 2-29 
file handles 1-16 
File I/O API 

extend file I/O API 1-4 
standard file I/O API 1-2 
File I/O bit, FIO 1-13 
file image 1-12 
file image, mini-FSD 4-9 
file information 2-70 
file instance, open files 1-21 
file lock request, cancel 2-6 
file search parameters, fsfsd 1-21 
file search parameters, fsfsi 1-21 
file search records, data structures 1-21 
file search structures 1-19 
file size, change 2-60 
file system control 2-47 
file system driver, FSD 1-2 
file system information 2-50 
file system initialization 2-51 
file version levels 1-16 
file-system-dependent data 1-19 
file-system-independent data 1-19 
FILEIO, File I/O bit 1-13 
find character in string 3-20 
find matching file name 2-33, 2-37, 2-39 
find-notify handle, close 2-41 
find-notify handle, open 2-42 
flush cache buffers 2-46 
FORMAT 1-7 
free segment 3-43 
FS Helper Functions 
FSH_ADDSHARE 3-3 
FSH_CALLDRIVER 3-5 


FS Helper Functions (continued) 
FSH_CANONICALIZE 3-7 
FSH_CHECKEANAME 3-9 
FSH_CRITERROR 3-10 
FSH_DEVIOCTL 3-12 
FSH_DOVOLIO 3-14 
FSH_DOVOLI02 3-17 
FSH_EXTENDTIMESLICE 3-19 
FSH_FINDCHAR 3-20 
FSH_FINDDUPHVPB 3-21 
FSH_FORCENOSWAP 3-22 
FSH_GETPRIORITY 3-24 
FSH_GETVOLPARM 3-25 
FSHJNTERR 3-26 
FSHJOBOOST 3-27 
FSHJOSEMCLEAR 3-28 
FSHJSCURDIRPREFIX 3-29 
FSH_LOADCHAR 3-30 
FSH_NAMEFROMSFN 3-31 
FSH_PREVCHAR 3-32 
FSH_PROBEBUF 3-33 
FSH_QSYSINFO 3-35 
FSH_QUERYOPLOCK 3-37 
FSH_QUERYSERVERTHREAD 3-38 
FSH_REGISTERPERFCTRS 3-39 
FSH_REMOVESHARE 3-40 
FSH_SEGALLOC 3-41 
FSH_SEGFREE 3-43 
FSH_SEGREALLOC 3-44 
FSH_SEMCLEAR 3-45 
FSH_SEMREQUEST 3-46 
FSH_SEMSET 3-48 
FSH_SEMSETWAIT 3-49 
FSH_SEMWAIT 3-50 
FSH_SETVOLUME 3-51 
FSH_STACKSPACE 3-52 
FSH_STORECHAR 3-53 
FSH_UPPERCASE 3-54 
FSH_WILDMATCH 3-55 
FSH_YIELD 3-56 
summary 3-1 
FS helpers 1-2 
FSA_LOCK 1-13 
FSA_REMOTE 1-13 
FSD entry points 

FS_ALLOCATEPAGESPACE 2-3 
FS_ATTACH 2-4 
FS_CANCELLOCKREQUEST 2-6 
FS_CHDIR 2-7 
FS.CHGFILEPTR 2-10 
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FSD entry points (continued) 
FS_CLOSE 2-12 
FS_COMMIT 2-13 
FS_COPY 2-15 
FS_DELETE 2-17 
FS_DOPAGEIO 2-18 
FS_EXIT 2-20 
FS_FILEATTRIBUTE 2-21 
FS_FILEINFO 2-23 
FS_FILEIO 2-26 
FS_FILELOCKS 2-29 
FS_FINDCLOSE 2-32 
FS_FINDFIRST 2-33 
FS_FINDFROMNAME 2-37 
FS_FINDNEXT 2-39 
FS_FINDNOTIFYCLOSE 2-41 
FS_FINDNOTIFYFIRST 2-42 
FS_FINDNOTIFYNEXT 2-44 
FS_FLUSHBUF 2-46 
FS_FSCTL 2-47 
FS_FSINFO 2-50 
FSJNIT 2-51 
FSJOCTL 2-52 
FS_MKDIR 2-54 
FS_MOUNT 2-56 
FS_MOVE 2-58 
FS_NEWSIZE 2-60 
FS_NMPIPE 2-61 
FS_OPENCREATE 2-65 
FS_OPENPAGEFILE 2-68 
FS_PATHINFO 2-70 
FS_PROCESSNAME 2-72 
FS_READ 2-73 
FS_RMDIR 2-75 
FS_SETSWAP 2-76 
FS_SHUTDOWN 2-77 
FS_VERIFYUNCNAME 2-79 
FS_WRITE 2-80 
summary 2-1 
FSD version number 1-13 
FSD, file system driver 1-2 
fsfsd, file search parameters 1-21 
fsfsi, file search parameters 1-21 
FSH_CHECKEANAME 1-10 
FSFIJJPPERCASE 1-10 
function calls, file system 1-16 
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GEAList 1-10 
GEAs 1-10 

H 

hard error, signal 3-10 

helper callouts, FSDs (summary) 3-1 

hVPB 3-21 

I 

I/O event semaphore, clear 3-28 
IFS = statement 1-16 
IFS Commands 

IFS= statement 1-16 
IFS partition 1-6 
IFS=, CONFIG.SYS 1-13 
initialization, file system 2-51 
initialization, FSD 1-13 
INT19H 4-2 
internal errors 3-26 
interrupts 1-22 

IOCTL request to device driver 3-12 
ipl mechanism 1-6 
IPL, remote 4-1 

K 

kernel mode 1-22 

L 

load character 3-30 
loading a file system 1-16 
loading device drivers and FSDs 1-6 
loading FSDs 1-13 

M 

make subdirectory 2-54 
matching wildcards 3-55 
meta characters 
micro-IFS, FAT 4-2 
mini-FSD 4-1 
mini-FSD Entry Points 
MFS_CHGFILEPTR 4-11 
MFS_CLOSE 4-12 
M FSJNIT 4-13 
MFSJDPEN 4-15 
MFS_READ 4-16 
MFS_TERM 4-17 
summary 4-10 
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mini-FSD helpers 

MFShLCALLRM 4-19 
MFSFLDOVOLIO 4-20 
MFSHJNTERR 4-21 
MFSH_LOCK 4-22 
MFSH_PHYSTOVIRT 4-23 
MFSH_SEGALLOC 4-24 
MFSH_SEGFREE 4-25 
MFSFLSEGREALLOC 4-26 
MFSH_SETBOOTDRIVE 4-27 
MFSHJJNLOCK 4-28 
MFSH_UNPHYSTOVIRT 4-29 
MFSH_VIRT2PHYS 4-30 
summary 4-18 

monitor file/directory changes, begin 2-42 

monitor file/directory changes, continue 2-44 

monitor file/directory changes, end 2-41 

mount volumes 2-56 

mount, force 3-51 

mounting a volume 1-5 

move a file or subdirectory 2-58 

move a file's position pointer 2-10 

multi-function file I/O 2-26 

N 

name shared set 3-3, 3-37, 3-38, 3-40, 3-52 
named pipe operation, remote 2-61 
names, FSDs 1-12 

o 

open a file 2-65 

open file parameters, sffsd 1-21 

open file parameters, sffsi 1-21 

open files, data structures 1-20 

openmode parameter 2-65 

OS/2 loader 4-2 

OS2BOOT 4-2 

OS2KRNL 4-2 

OS2KRNL interface 4-5 

OS2LDR 4-2 

OS2LDR interface 4-4 

P 

paging file size, change 2-3 
paging file, create 2-68 
paging file, open 2-68 
paging I/O, operations 2-18 


path name 3-31 
path name, canonical form 3-7 
PDB, program data block 1-21 
PID, process ID 1-21 
POST 4-2 

power-on-self-test 4-2 
PREFVIEW, registration 3-39 
process file name 2-72 
process ID, PID 1-21 
program data block, PDB 1-21 
pseudo-character devices 1-7 

Q 

query/set a file's information 2-23, 2-70 
query/set file attribute 2-21 

R 

read from a file 2-73 
RECOVER 1-7 
register usage, FSDs 1-22 
remote file system, REMOTE 1-13 
remote IPL 4-1 

remote named pipe operation 2-61 
REMOTE, remote file system 1-13 
removable media, volume management 1-5 
remove subdirectory 2-75 
request router, file system 1-2 
request semaphore 3-46 
RIPL 4-1 

s 

segment size 3-44 
Semaphore FS helpers 
FSH_SEMCLEAR 3-45 
FSH_SEMREQUEST 3-46 
FSH_SEMSET 3-48 
FSH_SEMSETWAIT 3-49 
FSH_SEMWAIT 3-50 
set and wait for semaphore 3-49 
set semaphore 3-48 
sffsd, open file parameters 1-21 
sffsi, open file parameters 1-21 
SFN 3-31 
SFT 1-19 

shared set, name 3-3, 3-37, 3-38, 3-52 

shutdown file system 2-77 

special considerations, bootable IFS 4-9 
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ST_CREAT, time stamp flags 1-22 
ST_PCREAT, time stamp flags 1-22 
ST_PREAD, time stamp flags 1-22 
ST_PWRITE, time stamp flags 1-22 
ST_SREAD, time stamp flags 1-22 
ST_SWRITE, time stamp flags 1-22 
stack usage, FSDs 1-22 
standard file I/O API 1-2 
store character 3-53 
subdirectory, make 2-54 
swap segments into memory 3-22 
swap-file ownership 2-76 
SYS 1-7 

system file table 1-19 
system information 3-35 
system interfaces, FSD 1-18 
system relationships, ifs 1-1 


vpfsd, volume parameters 
vpfsi, volume parameters 


w 

wait for semaphore 3-50 
wildcards 3-55 
write to a file 2-80 

Y 

yield CPU 3-56 


T 

time stamp flags 1-22 
timestamping 1-22 
time, format of 1-17 


u 

UNC server, verify 2-79 
UNC, Universal Naming Convention bit 1-13 
Universal Naming Convention bit, UNC 1-13 
uppercase asciiz string 3-54 
user address 3-33 
Utility Support 
CHKDSK 1-7 
FORMAT 1-7 
RECOVER 1-7 
SYS 1 -7 


V 

valid user address 3-33 
validation of input parameters 3-1 
volume 1-19 
volume I/O 3-14 

volume IOCTL request to device driver 3-17 
volume management, removable media 1-5 
volume parameter block 1-5, 1-19 
volume parameters, vpfsd 1-19 
volume parameters, vpfsi 1-19 
volume, force mount 3-51 
VPB 1-5,1-19,3-25 
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+++EDF074W Revision for REF1D=0S24 out of sequence - EREV tag ignored. (Page 3-52 File: IFSFl 
ELP) 

DSMMOM3971 '.EDFERVBR' WAS IMBEDDED AT LINE 2036 OF 'IFSHELP' 

DSMMOM3971 'IFSHELP' WAS IMBEDDED AT LINE 123 OF 'OS2IFS20' 

DSMBEG323I STARTING PASS 2 OF 2. 

+++EDF074W Revision for REF1D=0S24 out of sequence - EREV tag ignored. (Page 3-52 File: IFSH 
ELP) 

DSMMOM397I ’.EDFERVBR' WAS IMBEDDED AT LINE 2036 OF ’IFSHELP' 

DSMMOM3971 ’IFSHELP’ WAS IMBEDDED AT LINE 123 OF ’OS2IFS20' 



